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Revision H documents the Math Library for NOS/VE at release level 1.4.1, PSR level 
716. This revision obsoletes all previous editions. 


This revision documents the following new features: 
e C language support. 
@ Enhanced CYBIL support. 


@ Performance improvements to the following math functions: 


ACOS 
ALOG 
ALOG10 
ASIN 
ATAN 
COS 
EXP 
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SQRT 
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e Algorithm changes to functions DTOI and XTOI. 
This revision also includes the following organizational changes: 


@ Number types, calling routines, error handling, scalar classification tables, calls 
from supported languages, and vector processing modules have been restructured as 
separate chapters. 


@ Short examples of each function have been added to illustrate the required number 
of arguments and number types. 


e A bibliography has been added. 
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About This Manual 


This manual describes the math functions available in the CONTROL DATA® Common 
Modules Mathematical Library (CMML), referred to in this manual as the Math 
Library. 


These math functions can be accessed by programs written in Ada, APL, Assembler, 
BASIC, C, CYBIL, FORTRAN Version 1, FORTRAN Version 2, LISP, Pascal, and 
Prolog. The Math Library is available under Control Data’s Network Operating 
System/Virtual Environment (NOS/VE) operating system and can also be accessed from 
Control Data’s UNIX! Virtual Environment (VX/VE) operating system. See the C for 
NOS/VE Usage manual for information about the C/VE Math Library. 


Audience 


To use the information in this manual, you should be familiar with the programming 
language from which you plan to call Math Library functions and with the NOS/VE® 
or VX/VE® operating system. In addition, you should have a basic knowledge of 
exponentiation, logarithms, trigonometry, and other functional areas depending upon 
how you plan to use the Math Library. 


1. UNIX is a registered trademark of AT&T. 
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Manual Organization 


This manual is organized into the following chapters: 


Chapter 1 - Introduction 


Introduces the Math Library and its mathematical and exponential functions. 
Defines the Math Library and its uses. Discusses strengths and limitations. 
Categorizes the functions. Explains entry points. 


Chapter 2 - Number Types 


Describes the number types used by the Math Library: integer, single precision 
floating-point, double precision floating-point, and complex. 


Chapter 3 - Calling Routines 
Describes the call-by-reference and call-by-value calling routines. 


Chapter 4 - Calls From Languages 


Provides examples of how these functions can be accessed by Ada, Assembler, C, 
and CYBIL programs. Also discusses other languages such as FORTRAN Version 1, 
FORTRAN Version 2, Pascal, APL, BASIC, COBOL, LISP, and Prolog. 


Chapter 5 - Error Handling 


Describes error handling for scalar processing including errors caused by bad input 
and inaccuracy caused by computer approximations. Contrasts call-by-reference and 
call-by-value error handling. 


Chapter 6 - Scalar Classification Tables 


Provides classification tables for easy identification of types of arguments, type of 
results, input domains, output ranges, and other detailed information. 


Chapter 7 - Vector Processing 


Describes vector processing and how it is used including hardware selection and 
error handling. Provides tables that summarize specific vector processing features. 


Chapter 8 - Function Descriptions 


Presents the functions in alphabetical order with specific information about the 
purpose of each function, the handling of the calling routines, and applicable 
algorithmic or error handling information. Short examples are provided to illustrate 
the required number of arguments and number types. 


Chapter 9 - Auxiliary Routines 


Presents detailed information on auxiliary routines that are called only by other 
math functions (for example, most of the computation for DTANH is performed in 
function DEULER). 
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Additional information is available in the following appendixes: 


Appendix A - Glossary 
Defines commonly-used terms and phrases. 


Appendix B - Related Manuals 

Lists manuals related to the Math Library including NOS/VE manuals and 
applicable language manuals. 

Appendix C - ASCII Character Set 

Provides the standard ASCII character set. Additional character sets are available 
in the applicable language manuals. 

Appendix D - Bibliography 


Lists mathematical reference works that were used as sources for algorithms or 
provide related background information. 
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Typographical Conventions 
This manual uses the following typographical conventions: 


In formulas, a horizontal ellipsis indicates that the preceding item can be 
repeated as necessary. 


* In formulas, an asterisk indicates multiplication. 
i In formulas, two successive asterisks indicate exponentiation. 


| | In formulas, vertical bars indicate the absolute value of the quantity. 


() In intervals, parentheses indicate an open interval (the end points are not 
included). 

[] In intervals, brackets indicate a closed interval (the end points are included). 

(] In intervals, closure by a left parenthesis and a right bracket includes the 


right end point, but not the left end point. 


[ ) In intervals, closure by a left bracket and a right parenthesis includes the 
left end point, but not the right end point. 


italic Used for special emphasis (for example, to highlight C data types and C 
type statement names). 

Mathematical Conventions 

This manual uses the following mathematical conventions: 


@ All numbers used in this manual are decimal unless otherwise indicated. Other 
number systems are indicated by a notation after the number (for example, FA34 
hexadecimal). 


@ All references to logarithm (log) are base e unless otherwise indicated. 


@ All references to infinite values include positive and negative infinity unless 
otherwise indicated. 


For rules about standard and nonstandard floating-point numbers, see Floating-Point 
Computation Rules in chapter 2, Number Types. 
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Submitting Comments 


The last page of this manual is a comment sheet. Please use it to give us your opinion 
of the manual’s. usability, to suggest specific improvements, and to report technical or 
typographical errors. If the comment sheet has already been used, you can mail your 
comments to: 


Control Data Corporation 
Technical Publications 

P. O. Box 3492 

Sunnyvale, California 94088-3492 


Please indicate whether you would like a written response. 


Also, if you have access to SOLVER, an online facility for reporting problems, you can 
use it to submit comments about the manual. For example, use FN8 as the product 
identifier for problems that are related to FORTRAN Version 1 and FV8 as the 

' product identifier for problems related to FORTRAN Version 2. 


In Case You Need Assistance 


Control Data’s CYBER Software Support maintains a hotline to assist you if you have 
trouble using our products. If you need help beyond that provided in the documentation 
or find that the Math Library for NOS/VE does not perform as described, call us at 
one of the following numbers and a support analyst will work with you. 


From the USA and Canada: (800) 345-9903 
From other countries: (612) 851-4131 


The preceding numbers are for help on product usage. Address questions about the 
physical packaging and/or distribution of printed manuals to Literature and Distribution 
Services at the following address: 


Control Data Corporation 
Literature and Distribution Services 
308 North Dale Street 

St. Paul, Minnesota 55103 


or you can call (612) 292-2101. If you are a Control Data employee, call 
CONTROLNET® 243-2100 or (612) 292-2100. 
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Introduction 1 


This manual describes the mathematical functions available in Control Data’s Common 
Modules Mathematical Library (CMML). CMML, referred to as the Math Library in 
this manual, contains a wide assortment of mathematical functions. 


These functions can be accessed by programs written in Ada, APL, Assembler, BASIC, 
C, CYBIL, FORTRAN Version 1, FORTRAN Version 2, LISP, Pascal, and Prolog. See 
chapter 4, Calls From Languages, for detailed information and examples of how to call 
Math Library functions from various languages. 
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Introduction 


Figure 1-1 shows the relationship of the Math Library to the NOS/VE operating 
system. The NOS/VE Math Library environment, in addition to the compilers listed 
above, includes the System Command Language (SCL), the NOS/VE block-structured 
interpreter, LIB99, a library of subroutines and functions that can be called from 
FORTRAN (or Ada through FORTRAN), and the Debug utility. 


Terminal 
User 


System 
Command 
Language 


Source 
Program 


Compiler 


Executable 
Object Program 


od 
' Printed 
Output 
System 
Math Command Debug 
Library Language Utility 


Figure 1-1. NOS/VE Math Library Environment 
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Functions Available 


Functions Available 


The Math Library provides approximately 100 math functions. In order to provide an 
overview, the NOS/VE Math Library functions are categorized in this manual as 
follows: 


@ Exponential 

® Logarithmic 

e Trigonometric 

@ Hyperbolic 

® Conversion and maximum/minimum 
e Bit manipulation 

@ Random number 

® Error 


The above categories are not precisely defined (for example, exponentiation is used in 
many of the trigonometric algorithms), but these categories are provided so you can 
more easily understand the contents of the Math Library. 


See chapter 6, Scalar Classification Tables, for tables that categorize the available 
functions according to the above list. See chapter 8, Function Descriptions, for an 
alphabetical presentation of each function including a description, a discussion of the 
calling routines, algorithmic and error analysis information, and the effects of 
argument error, if applicable. 


Additional FORTRAN for NOS/VE LIB99 functions can be called from FORTRAN 
Version 1 or FORTRAN Version 2. These functions in turn can be accessed by any 
language that can interface with FORTRAN (for example, Ada and CYBIL can make 
calls to FORTRAN). LIB99 can perform the following tasks: 


@ Perform basic vector arithmetic 

@ Perform basic matrix algebra 

@ Solve linear systems of equations 
® Compute Fast Fourier Transforms 
e Sort lists 


® Compute eigenvalues and eigenvectors 
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Functions Available 


Exponential Functions 


The exponential functions are as follows: 


Function Description 

CEXP Complex exponential (base e) 

CSQRT Complex square root 

DEXP Double precision exponential (base e) 

DSQRT Double precision square root 

DTOD Exponentiation with double precision base and double precision 
exponent 

DTOI Exponentiation with double precision base and integer exponent 

DTOX Exponentiation with double precision base and real exponent 

DTOZ Exponentiation with double precision base and complex exponent 

EXP Exponential (base e) 

ITOD Exponentiation with integer base and double precision exponent. 

ITOI Exponentiation with integer base and integer exponent 

ITOX - Exponentiation with integer base and real exponent 

ITOZ Exponentiation with integer base and complex exponent 

SQRT Square root ; 

XTOD Exponentiation with real base and double precision exponent 

XTOI Exponentiation with real base and integer exponent 

XTOX Exponentiation with real base and real exponent 

XTOZ Exponentiation with real base and complex exponent 

ZTOD Exponentiation with complex base and double precision exponent 

ZTOI Exponentiation with complex base and integer exponent 

ZTOX Exponentiation with complex base and real exponent 

ZTOZ Exponentiation with complex base and complex exponent 


Chapters 6 and 8 provide detailed information about each of these functions. Chapter 6 
provides two tables with exponentiation information including the number types of the 
results of the exponentiation functions. 


Logarithmic Functions 


The logarithmic functions are as follows: 


Function Description 

ALOG Natural logarithm (base e) 

ALOG10 Common logarithm (base 10) 

CLOG Complex natural logarithm (base e) 

DLOG Double precision natural logarithm (base e) 
DLOG10 Double precision common logarithm (base 10) 


Chapters 6 and 8 provide detailed information about each of these functions. 
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Functions Available 


Trigonometric Functions 


The trigonometric functions return values in radians except for COSD, SIND, and 
TAND which return values in degrees. The trigonometric functions are as follows: 


Function Description 

ACOS Inverse cosine 

ASIN Inverse sine 

ATAN Inverse tangent 

ATAN2 Inverse tangent of the ratio of two arguments 
CCOS Complex cosine 

COS Cosine 

COSD Cosine in degrees 

COTAN Cotangent 

CSIN Complex sine 

DACOS Double precision inverse cosine 
DASIN Double precision inverse sine 
DATAN Double precision inverse tangent 
DATAN2 Double precision inverse tangent of the ratio of 2 arguments 
DCOS Double precision cosine 
DSIN Double precision sine 

DTAN Double precision tangent 

SIN Sine 

SIND Sine in degrees 

TAN Tangent 

TAND Tangent in degrees 


Chapters 6 and 8 provide detailed information about each of these functions. 


Hyperbolic Functions 


The hyperbolic functions are as follows: 


Function Description 

ATANH Inverse hyperbolic tangent 

COSH Hyperbolic cosine 

DCOSH Double precision hyperbolic cosine 
DSINH Double precision hyperbolic sine 
DTANH Double precision hyperbolic tangent 
SINH Hyperbolic sine 

TANH Hyperbolic tangent 


Chapters 6 and 8 provide detailed information about each of these functions. 
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Functions Available 


Conversion and Maximum/Minimum Functions 


The conversion and maximum/minimum functions are as follows: 


Function 


ABS 
AIMAG 
AINT 
AMOD 
ANINT 


CABS 
CONJG 


DABS 
DDIM 
DIM 
DINT 
DMOD 
DNINT 
DPROD 
DSIGN 


IABS 
IDIM 
IDNINT 
ISIGN 


MOD 
NINT 
SIGN 


Description 


Absolute value 

Imaginary part of a complex argument 

Truncation 

Returns the remainder of a ratio (uses real numbers) 
Nearest whole number 


Complex absolute value 
Conjugate 


Double precision absolute value 

Double precision positive difference 

Positive difference 

Double precision truncation 

Returns the remainder of a ratio (uses double precision numbers) 
Double precision nearest whole number 

Double precision product 

Double precision transfer of sign 


Integer absolute value 

Integer positive difference 
Double precision nearest integer 
Integer transfer of sign 


Returns the remainder of a ratio (uses integers) 
Nearest integer 


Transfer of sign 


Chapters 6 and 8 provide detailed information about each of these functions. 
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Functions Available 


Bit Manipulation Functions 


The bit manipulation functions are as follows: 


Function Description 

EXTB Extract bits 

INSB Insert bits 

SUM1S Sum of 1 bits in one word 
NOTE 


The number of bits in a CYBER 180 word is always 64. 


Chapters 6 and 8 provide detailed information about each of these functions. 


Random Number Functions 


The random number functions are as follows: 


Function Description 

RANF Generates the next random number in a series 
RANGET Returns the.current random number seed of a task 
RANSET Sets the seed of the random number generator 


Chapters 6 and 8 provide detailed information about each of these functions. 


Error Functions 


The error functions are as follows: 


Function Description 
ERF Computes the error function 
ERFC Computes the complementary error function 


Chapters 6 and 8 provide detailed information about each of these functions. 
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Entry Point 


Depending upon the language you use, you may want to call a Math Library function 
by an entry point other than its function name. (Assembly language calls cannot be 
made to function names.) Math Library functions have two types of entry point: 
call-by-reference and call-by-value. For example, the function ABS can be called by the 
call-by-reference entry point MLP$RABS (or ABS) or by the call-by-value entry point 
MLP$VABS. (See chapter 4, Calls From Languages, for an example.) 


NOTE 


The function name (for example, ABS) is also a call-by-reference entry point. 
Figure 1-2 shows the naming conventions for entry points. 


Call-by-Reference Pattern 


MLP$ RABS 


et 


Function 
Prefix R Name 
for 


Reference 


Call-by-Value Pattern 


MLP$ WABS 


Standard ] 
V 


Prefix 


Figure 1-2. Pattern Diagram for Entry Points 
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Number Types a 2 


This chapter discusses how the Math Library functions perform computations on the 
following number types: 


-@ Integer 

e Single precision floating-point (real) 

@ Double precision floating-point (long real) 
@ Complex 


The following paragraphs describe how these number types are used by the Math 
Library. 
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Integer 


‘Integer 


An integer is a one-word, right-justified, two’s complement 64-bit representation of all 
integers from —(2**63) through (2**63)-1. See figure 2-1 for an illustration of 8-byte 
integer format. All 8-byte integers up to the absolute value of 9,223,372,036,854,775,807 
are accepted by the Math Library. 


The implementation of type integer varies across languages. The C language, for 
example, has a 32-bit integer (short int) and a 64-bit long integer (iné). (For an 
explanation of how to use the left-bit-shift (<<) operator to left justify short int, see C 
Calling the Math Library in chapter 4, Calls From Languages.) 


INTEGER 


Figure 2-1. Bit Diagram of 8-Byte Integer Format 
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Single Precision Floating-Point Numbers 


A single precision floating-point number consists of a sign bit, S, which is the sign of 
the fraction, a signed. biased exponent (15 bits), and a fraction (48 bits) which is also 
called a coefficient or a mantissa. Figure 2-2 illustrates the internal representation of 
this format. | 


EXPONENT FRACTION 
(15 bits) (48 bits) 


Figure 2-2. Bit Diagram of Single Precision Floating-Point Format 


Single precision floating-point numbers consist of two types: standard and nonstandard. 


Single Precision Standard Numbers 


Standard numbers are numbers that have exponents in the range of 3000 hexadecimal 
through 4FFF hexadecimal, inclusive, and have a nonzero fraction or 0. Standard 
numbers can be normalized or unnormalized. A normalized standard number has a 1 
(one) in bit position 16 (the most significant bit of the fraction), where bit position zero 
is the leftmost bit. | 


The range in magnitude, M, covered by standard, normalized single precision numbers 
is as follows: 


-1* (1 -2** -48) * 2** 4095 <= M <= -2** -4097 
0 
2** — 4097 <= M <= (1 -2*# -48)*2**4095 


The above range provides approximately 14.4 decimal digits of precision. 
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Single Precision Floating-Point Numbers 


Single Precision Nonstandard Numbers 
Nonstandard floating-point numbers have the following representations: 


® A nonzero unnormalized floating-point number with a zero fraction and a standard 
exponent 


e A floating-point number with an exponent in the range 5000 through 6FFF 
hexadecimal (+infinite) and D000 through EFFF hexadecimal (—infinite) 


e A floating-point number with an exponent in the range 7000 through 7FFF 
hexadecimal (+ indefinite) and F000 through FFFF (—indefinite) . 


e A nonzero floating-point number with an exponent in the range 0000 through OFFF 
hexadecimal (+Z1) and 8000 through 8FFF (—Z1) 


e A floating-point number with an exponent in the range 1000 through 2FFF 
hexadecimal (+2Z2) and 9000 through AFFF (—Z2) 


The last item includes a sign bit followed by 63 zero bits. Nonstandard numbers are 


not used in computations, but some are returned as default error values as described 
later in this chapter under Default Error Values. 
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Double Precision Floating-Point Numbers 


A double precision floating-point number consists of two words, each a single precision 
floating-point number. The coefficient of the second word is considered to be an 
extension of the fraction of the first word, yielding a 96-bit fraction. The exponent of 
the second word following an arithmetic operation is identical to that of the first word. 
The number type of the first word determines the type of the second word. 


See figure 2-3 for an illustration of the internal representation of a double precision 
floating-point format. 


EXPONENT LEFT HALF OF FRACTION 
(15 bits) (48 bits) 


(not used as 
input but 
provided on output) 


RIGHT HALF OF FRACTION 
(48 bits) 


Figure 2-3. Bit Diagram of Double Precision Floating-Point Format 


The range in magnitude, M, covered by standard, normalized double precision numbers 
is: 


-1* (1 -2** -96) * 2** 4095 <= M <= -2** -4097 
0 
2** - 4097 <= M <= (1 -2** -96)*2*#*4095 
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Double Precision Floating-Point Numbers 


The above range yields approximately 28.9 decimal digits of precision. See figure 2-4 
for a summary of NOS/VE floating-point representation. 


Hexadecimal Exponent Including Coefficient Sign 
Actual Exponent (To The Base 2) 
Input Arguments 
Results 
Indefinite 7000.0 0 


212,287 


Overflow Mask = 0: 5000.0 —>0 
Overflow Mask = 1: As Shown 


24,096 infinite 


Coefficient 
Sign Equal 
To O 
(Positive 


Numbers) Standard As Shown 


2-4,097 


Underflow Mask = 0: 0000.0--0 
Underflow Mask = 1: As Shown 
2-12,288 


2-12,2B8 
2-4,097 


20 


' 


24,095 


Not Applicable 


Underflow Mask = 0: 0000.00 
Underflow Mask = 1: As Shown 


Coefficient 
Sign Equal 
To 1 
(Negative 
Numbers) 


Standard As Shown 


24,096 


a Overflow Mask = 0: D000.0-> 0 
Infinite Overflow Mask = 1: As Shown 


212,287 


indefinite 7000.0 —-0 


Figure 2-4. Summary of NOS/VE Floating-Point Representation 
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Complex Numbers 


A complex number consists of two words, each a single precision floating-point number. 
The first word represents the real part of the complex number; the second word 
represents the imaginary part. 


A complex number is considered to be indefinite if either the real or imaginary part is 
indefinite. Similarly, a complex number is considered to be infinite if either the real or 
imaginary part is infinite. 


Floating-Point Computation Rules 


Throughout this manual, unless otherwise documented, the following rules apply to 
floating-point computation: 


1. If a standard form of a number type is used in a computation, a standard form of 
the same type results, unless the answer computed exceeds the range of values for 
standard numbers or if a mathematically invalid operation is attempted. 


2. If a nonstandard number other than zero is used in a computation, or if the limits 
to a standard form of a number type are exceeded, error handling occurs, unless 
various nonstandard numbers are within the domain of the function. 

Default Error Values 

The Math Library uses the following default error values: 

® Positive indefinite (+IND) 

@ Negative indefinite (-IND) 

@ Zero (0) 

® Positive infinity (+ INF) 

® Negative infinity (-INF) 


Most of the Math Library functions have a default error value of positive indefinite. 
The following functions have a default error value of zero: CCOS, DEXP, ERFC, EXP, 
IDIM, IDNINT, ITOI, MOD, and NINT. 
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Inline Versus Out-of-Line Routines 


Calling Routines oe ‘ 3 


Routines and Calls 


The Math Library functions are predefined functions that can be called from Ada, APL, 
Assembler, BASIC, CYBIL, FORTRAN Version 1, FORTRAN Version 2, LISP, Pascal, 
or Prolog programs according to the attributes of the calling language. Some functions 
are not available to every language; see chapter 4, Calls From Languages, for 
information about specific languages. 


The Math Library provides two types of calling routines: 

@ Call-by-reference 

@® Call-by-value 

These calling routines are discussed in the following paragraphs. 


NOTE 


This chapter deals with scalar processing only. For a discussion of vectors, see 
chapter 7, Vector Processing. 
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Call-by-Reference 


A call to a call-by-reference routine consists of the following process: 


1p 
2. 


5. 


The user program sets up a parameter list (argument list) in memory. 


The call to the instruction causes the first-word address to be stored in register A4 
as the routine is invoked. 


The call-by-reference routine is called through one of two entry points (for example, 
ABS or MLP$RABS). Argument error processing is set up in this routine. 


If the argument list is valid, the routine calls or branches to the call-by-value 
routine, depending on the function. 


The call-by-value routine performs the appropriate computation and returns a result. 


If the argument list is invalid, the call-by-value routine is not executed and an error 
message is returned. See the appropriate language manual (printed or online) for 
information about a compilation message. See the NOS/VE Diagnostic Messages manual 


(printed or online) for information about a runtime message. 


Figure 3-1 is a Nassi-Shneiderman chart! illustrating the logical flow of the 


call-by-reference routine. 


NOTE 


Call-by-reference is synonymous with call-by-address. 


1. Nassi-Shneiderman charts (also called Chapin charts) are read like flow charts: a rectangle indicates a 
process, an inverted isosceles triangle indicates a decision, and a right triangle indicates a branch from a 
decision. 
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Call-by-Reference 


Call-by-Reference 
Argument List 


2 Stored in Register A4 oe 


ERROR 
Cali-by-Value 
MESSAGE 
Routine 


Aijgorithm 
Analyze 
Computation 
Return 


Figure 3-1. Call-by-Reference Logic Diagram (Scalar) 
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Call-by-Value 


A call to a call-by-value routine consists of the following process: 


1. 


The user program sets up a parameter list (argument list) directly into the X 
registers before the routine is invoked. 


The call to the instruction causes the first word of the first argument to be entered 
into register X2; the remaining words of each argument are entered into the 
registers successively. 


For example, the calling procedure for the exponentiation function ITOD 
(exponentiation with integer base and double precision exponent) uses registers X2, 
X3, and X4. Register X2 holds the integer base, and registers X3 and X4 hold the 
double precision exponent. 


The first and second words of a complex argument contain the real and imaginary 
parts, respectively. The first and second words of a double precision argument 
contain the high-order and low-order bits, respectively. 


The call-by-value routine performs the appropriate computation, and when valid 
computations occur, returns a result. The result is returned in registers XE and 
XF. 

One-word results (type integer and single precision) are returned in register XF. 
Two-word results (type double precision and complex) are returned in registers XE 
and XF; the second word is stored in register XF. 


If the call-by-value routine is called directly and the arguments are out-of-range, the 
job aborts during the computation and an error message is returned. See the NOS/VE 
Diagnostic Messages manual (printed or online) for information about a runtime 
message. 


Figure 3-2 is a Nassi-Shneiderman chart? illustrating the logical flow of the 
call-by-value routine. 


2. Nassi-Shneiderman charts (also called Chapin charts) are read like flow charts: a rectangle indicates a 
process, an inverted isosceles triangle indicates a decision, and a right triangle indicates a branch from a 
decision. 
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Call-by-Value 


Call-by-Value 
Argument List 


Stored in X Registers 


Value Value 
in Range out of Range 


X Registers 


First Register 
ABORTS 
Word X2 


Second Register Check 
Word X3 Argument 
List 
Third Register 
Word X4 


Result Register 
(first word) XE 


Result 
One word Register Return 


(or second word) XF 


Return 


Figure 3-2. Call-by-Value Logic Diagram (Scalar) 
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Call-by-Reference Versus Call-by-Value Matrix 


Some languages, such as FORTRAN and Pascal, can access the Math Library through 
call-by-reference or call-by-value routines. Other languages can use only one type of 


routine. 


The language matrix provided as table 3-1 outlines the distinction between 
call-by-reference (addresses of arguments are passed) and call-by-value (values of 
arguments are passed) across the supported languages. 


Transparency is defined as the apparent invisibility of the Math Library. APL, BASIC, 
LISP, and Prolog programmers do not need to know that the Math Library exists 
unless they get a range or type error, or need to perform error analysis. 


FORTRAN and Pascal programmers have compile option EXPRESSION_ 
EVALUATION = REFERENCE which selects call-by-reference over call-by-value, but the 
functioning of the Math Library is essentially transparent. Ada, Assembler, C, and 
CYBIL programmers have a few programming options which are discussed in the 


following sections. 


Table 3-1. Language Matrix 
Languages (Providing Interfaces) 


Ada 
Assembler 
C 

CYBIL 


Languages (With Transparent Access) 


APL 

BASIC 

FORTRAN Version 1 
FORTRAN Version 2 
LISP 

Pascal 


Prolog 


Language (With No Access) 
COBOL 


3-6 Math Library 


Call-by-Reference 
Yes 


Yes 
Yes 
Yes 


Call-by-Reference 


Yes 


Call-by-Reference 


No 


Call-by-Value 
No 


Yes 
Yes 
Yes 


Call-by-Value 
Yes 


Yes 


Yes 


Call-by-Value 
No 
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Inline Versus Out-of-Line Routines 


Several of the NOS/VE compilers such as FORTRAN Version 1, FORTRAN Version 2, 
and Pascal have added some of the Math Library algorithms to their code generators; 
this inline process improves execution time significantly, but may slow down 
compilation slightly. 


The following functions are available to the FORTRAN and Pascal compilers as inline 
routines: 


ACOS ATAN SIN 
ALOG COs SQRT 
ALOG10 EXP TAN 
ASIN 


See chapter 4, Calls From Languages, for information about specific languages calling 
the Math Library. . 
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This chapter provides examples and explanations of how to call the Math Library from 
the supported languages. The Math Library functions can be called from the following 
languages: 


@e Ada 
e@ APL 


e Assembler 


e BASIC 
e Cc 
e CYBIL 


@ FORTRAN Version 1 
@® FORTRAN Version 2 


e LISP 
e@ Pascal 
e Prolog 


Many of these calls are transparent to the end user, but a working knowledge of the 
calling options could improve program design, performance, or accuracy. 
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Calls From Languages 


APL, BASIC, FORTRAN, LISP, Pascal, and Prolog provide interfaces to the Math 
Library that are transparent to the user. COBOL has no direct access to the Math 
Library. Table 4-1 summarizes how each language calls the Math Library. 


Table 4-1. 


Languages 
(Providing Interfaces) 


Ada 


Assembler 


C 


CYBIL 


Languages 
(With Transparent Access) 


APL 
BASIC 
FORTRAN Version 1 


FORTRAN Version 2 


LISP 
Pascal 
Prolog 
Language 


(With No Access) 
COBOL 


4-2 Math Library 


Language Summary 


Description 


Calls the Math Library through pragma MATH_ 
LIBRARY; also provides an interface to FORTRAN 
Version 1 or 2. Uses call-by-reference. See figure 4-1. 


Allows call-by-reference and call-by-value. See figure 
4-2. 


Allows call-by-reference and call-by-value. See figures 
4-3 and 4-4. 


Some functions can call with call-by-reference or 
call-by-value. Double precision functions can be called 
with call-by-reference only. See figure 4-5. 


‘Description 


No knowledge of the Math Library is necessary. 
No knowledge of the Math Library is necessary. 


Use EXPRESSION EVALUATION = REFERENCE for 
call-by-reference on the FORTRAN command; otherwise, 
call-by-value is used. See table 4-4 for a summary of 
FORTRAN functions. 


Use EXPRESSION_ EVALUATION = REFERENCE for 
call-by-reference on the VFORTRAN command; 
otherwise, call-by-value is used. Has array-processing 
intrinsic functions. See table 4-4 for a summary of 
FORTRAN functions. 


No knowledge of the Math Library is necessary. 


Use the EXPRESSION_ EVALUATION = REFERENCE 
parameter for call-by-reference on the PASCAL 
command; otherwise, call-by-value is used. 


No knowledge of the Math Library is necessary. 


Description 


The language cannot return a value from a function. 
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Ada Calling the Math Library 


Ada supports calls to the Math Library functions. For each Math Library subroutine to 
be called from Ada, the Ada program must provide the following: 


@ Ada Subprogram Declaration: 
subprogram_ specification ::= 
function identifier (formal_parameter_specifications) 
return type_mark 
e@ Ada Interface Specification: 
subprogram_body ::= pragma INTERFACE (MATH _ LIBRARY, identifier) 
The Ada subprogram declaration provides: 
@ The name of the Math Library function in the function identifier field 
@ The types of the formal parameters (in formal_parameter_specifications) 


@ The subtype of the returned value (the result subtype) in the type_mark field 


The name of the Math Library function must also appear as the identifier in the Ada 
interface specification. The name must be one of the Math Library function names. See 
table 4-1 for a summary of the input and output data types. 


The next section provides an Ada example. 
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Ada Subprogram Declaration and Interface Specification 


To use the Math Library function RANF (random number generator), enter the 
following Ada subprogram declaration and interface specification: 


function RANF return FLOAT; 
pragma INTERFACE (MATH_LIBRARY, RANF); 


The subprogram declaration tells the following: 

© RANF is the name of the Math Library function. 

e RANF has no formal input parameters (parameters of mode in). 
© The result is of type FLOAT (single precision real number). 
NOTE 


If an incorrect data type is passed to a Math Library function (for example, an 
INTEGER instead of a FLOAT), an incorrect value may be returned. Your program 
should check that the correct data type is passed. 


Figure 4-1 illustrates how to implement the Ada MATH_LIBRARY pragma interface 
(interface specification). Procedure CALL_MATHLIB has a pragma interface to the 
Math Library function SQRT. SQRT has one formal input parameter (parameter of 
mode in), x of type FLOAT. 


with TEXT_IO; use TEXT_IO; 


procedure CALL_MATHLIB is | 


function SQRT(x : in FLOAT) return FLOAT; 
pragma INTERFACE (MATH_LIBRARY, SQRT); 
package FLT_IO is new FLOAT_IO (FLOAT); 
use FLT_IO; 

y : FLOAT; 


begin — CALL_MATHLIB 


PUT_LINE ("Start Ada"); 

y := SQRT(225.0); 

PUT ("The square root of 225 is: "); 

PUT (y, fore => 2, aft => 2, exp => 0); 
NEW_LINE; 

PUT_LINE ("End Ada"); 


end CALL_MATHLIB; 


Figure 4-1. Ada Program Calling the Math Library 
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Ada Calling the Math Library 


With the Ada MATH_LIBRARY pragma interface, you can access the Math Library 
functions. Table 4-2 summarizes the Ada MATH_LIBRARY functions and their 
input-output data types. The table lists the following for each function: 


60486513 H 


Data Types for Ada MATH_LIBRARY Functions 


Description 


Inverse circular cosine 
Integer part 

Natural logarithm 
Common logarithm 
Nearest integer 


Inverse circular sine 
Inverse circular tangent 
Inverse hyperbolic _ 
tangent 

Inverse circular tangent 
of a ratio of two 
arguments 


Circular cosine 
Circular cosine in 
degrees . 
Hyperbolic cosine 
Circular cotangent 


Inverse circular cosine 
Inverse circular sine 
Inverse circular tangent 
Inverse circular tangent 
of a ratio of two 
arguments 

Circular cosine 


Hyperbolic cosine 
Positive difference 
Exponentiation function 
Positive difference 
Integer part 


Natural logarithm 
Common logarithm 
Nearest whole number 
Product 

Transfer of sign 


Circular sign 
Hyperbolic sine 


© Function name 
® Precision type 
® Description of the function 
@ Input type 
® Output type 
Table 4-2. 
Function Precision 
ACOS Single 
AINT Single 
ALOG Single 
ALOG10 Single 
ANINT Single 
ASIN Single 
ATAN . Single 
ATANH Single 
ATAN2 Single 
Cos Single 
COSD Single 
COSH Single 
COTAN Single 
DACOS Double 
DASIN Double 
DATAN Double 
DATAN2 Double 
DCOS Double 
DCOSH Double 
DDIM Double 
DEXP Double 
DIM Single 
‘DINT Double 
DLOG Double 
DLOGI10 Double 
DNINT | Double 
DPROD Double 
DSIGN Double 
_ DSIN Double 
DSINH Double 


Input Type 


FLOAT 
FLOAT 
FLOAT 
FLOAT 
FLOAT 


FLOAT 
FLOAT 


FLOAT 


FLOAT 


FLOAT 
FLOAT 


FLOAT 
FLOAT 


LONG_FLOAT 
LONG_FLOAT 
LONG_ FLOAT 
LONG_FLOAT 


LONG_ FLOAT 


LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 
FLOAT 

LONG_FLOAT 


LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 


LONG_FLOAT 
LONG_FLOAT 
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Output Type 


FLOAT 
FLOAT 
FLOAT 
FLOAT 
FLOAT 


FLOAT 
FLOAT 
FLOAT 


FLOAT 


FLOAT 
FLOAT 


FLOAT 
FLOAT 


LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 


LONG_FLOAT 


LONG_ FLOAT 
LONG_FLOAT 
LONG_FLOAT 
FLOAT 

LONG_FLOAT 


LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 
LONG_FLOAT 


LONG_FLOAT 
LONG_FLOAT 


(Continued) 
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Table 4-2. Data Types for Ada MATH_LIBRARY Functions (Continued) 


Function Precision Description Input Type Output Type 
DSQRT Double Square root LONG_FLOAT LONG_FLOAT 
DTAN  .__—s*ODouble Circular tangent LONG_FLOAT LONG_FLOAT 
DTANH Double Hyperbolic tangent LONG_FLOAT LONG_FLOAT 
ERF Single Error function FLOAT FLOAT 
ERFC Single Error function FLOAT FLOAT 
complement 
EXP Single Exponentiation FLOAT FLOAT 
EXTB _ Extract bits INTEGER INTEGER 
IDIM _ Positive difference of INTEGER INTEGER 
2 two integers 
IDNINT Double Nearest whole number LONG_FLOAT INTEGER 
INSB. — Insert bits INTEGER INTEGER 
ISIGN _ Integer transfer of sign INTEGER INTEGER 
NINT Single . Nearest whole number FLOAT INTEGER 
RANF _siSingle Random number _. None FLOAT 
generator 
RANGET _ Single Returns random number None ~ FLOAT 
seed 
RANSET _ Single Sets random number FLOAT FLOAT 
seed 
SIGN Single Transfer of sign FLOAT FLOAT 
SIN ' Single Circular sine FLOAT FLOAT 
SIND Single - Circular sine in degrees FLOAT FLOAT 
SINH Single Hyperbolic sine FLOAT FLOAT 
SQRT Single Square root FLOAT FLOAT 
TAN Single Circular tangent FLOAT FLOAT 
TAND Single Circular tangent in FLOAT FLOAT 
degrees 
TANH Single Hyperbolic tangent FLOAT FLOAT 


Ada Uses Call-by-Reference 


The call-by-reference interface is supported by NOS/VE Ada for the Math Library. The 
NOS/VE Ada compiler appends the call-by-reference prefix (MLP$R) to the abbreviated 
Math Library function name. 


In a call-by-reference computation, a parameter list is formed in memory and the 
first-word-address of this list is stored in register A4 before the routine is invoked. 
Additional Ada Functions 


Ada provides several other language defined functions. For example, exponentiation is 
provided with the exponentiation operator (**). Other functions such as mod (modulus) 
and rem (remainder) are provided as reserved words. See the Ada for NOS/VE 
reference or usage manual for additional information. 
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Calling FORTRAN and the Math Library From Ada _— 


- Ada supports calls to FORTRAN Version 1 and Version 2 subprograms. For each 
FORTRAN subprogram, the following Ada interface must be provided: 


Formal Grammar: 


subprogram_ specification ::= 
procedure identifier (formal_parameter_ specifications) 
| function identifier (formal_parameter_specifications) 
return type_mark 


subprogram_body :: 
pragma INTERFACE (FORTRAN, identifier) 


Through the pragma INTERFACE (FORTRAN, identifier), an Ada program can call a 
FORTRAN Version 1 or Version 2 intrinsic function or a Math Library function. 


For example, figure 4-1 could be modified to call SQRT through FORTRAN: 
pragma INTERFACE (MATH_LIBRARY, SQRT); 
The Ada FORTRAN interface has the following characteristics: 
@ FORTRAN subroutines and functions expect parameters to be passed by reference. 


@ The Ada compiler passes scalar parameters by value but array and string 
parameters by reference. 


@ When calling a FORTRAN subprogram, the Ada compiler passes, for scalar 
parameters, pointers to a copy of the value; for other types of parameters, the 
compiler passes pointers to the actual values. 


e The NOS/VE Ada compiler does not check the modes and types of the Ada actual 
parameters and FORTRAN formal parameters for agreement. 


Since in Ada the length of an array or a string parameter is always known at the 
time of the subprogram call, the Ada compiler can, when passing an address, pass the 
length of a string with a string address and the array descriptor with an array 
address. This allows parameters of type array or string to be declared in FORTRAN as 
either fixed or assumed size. 


Exponentiation Using Ada 


Ada provides the exponentiation operator (**), which is predefined for INTEGER, 
FLOAT, and LONG_FLOAT. Unlike FORTRAN, however, the right operand (the 
exponent) must be an integer for Ada exponentiation. The left operand (the base) can 
be any integer type or floating-point type, but not a fixed-point type. 


Calls to FORTRAN can be made if exponents of different types are required. For a 
summary of the exponentiation functions, see table 6-3 (in chapter 6). 
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Assembler Calling the Math Library 


The program illustrated in figure 4-2 calls the Math Library with assembly language. 
This program, identified as MATHEXM, illustrates both the call-by-reference and the 
call-by-value calling routines. 


mathexm 


ident 


This program shows both methods of calling the Math Library 
functions, call-by-reference and call-by-value. 


The binding section contains the links to external code and data. 
Its entries are set by the loader and the Object Code Utilities. 


use 
ref 
address 
ref 
address 
address 


use 
wseg align 
pi fioat 
one float 
two float 
result 
result2 


binding 


mip$rsin 


c,mip$rsin 


mip$vsin 


c,mip$vsin 
p,wseg 


working 
0,8 

3. 141592654 
1.00 

2.00 

bss2 8 
bssz 8 


starting procedure 


use 
def 
align 


ente 
callseg 
SX 

1x 

ente 
callseg 
Sx 
return 
end 


code 

prog. 

0,8 
a5,a3,data 
a0,a0, 16 
xa,a5,pi 
xb,a5,two 

xc, Xa 

xc, xb 

xc,a1,0 
ai,a1,8 
a4,a1,8 

x0, 0a5c( 16) 
sinr ,a3,a4 

xf ,a5,result1 
x2,a5,one 

x0, 0a5c( 16) 
sinv,a3,af 
xf,a5,result2 


prog 


- select the binding section 
. Gefine links to the SIN function 
. set the call-by-reference version 


- set the call-by-value version 
. the link to the working section 


- select working storage 
- ensure start at word boundary 


. A5 gets address of working section 

. allocate space for the parameter list 
. XA is loaded with the value of pi 

. XB is loaded with the value of 2.0 

. XA is copied to XC 

. XC <= pi/2 

. store the result in the stack 

. and its address one word later 

. set A4 to the address of the parameter list 
. save AQ-A5, XA-XC on the stack 

. Call MLP$RSIN 

. XF contains result of SIN(pi/2.0) 


load x2 with the value of 1.0 


. save AO-A5, XA-XC on the stack 
- parameter list not used 
. XF contains result of SIN(1.0) 


Figure 4-2, Assembler Program Calling the Math Library 
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C Calling the Math Library 


The C language programmer has access to both the NOS/VE Math Library and the 
C/VE Math Library. See the C for NOS/VE Usage Manual for information on how to 
call the C/VE Math Library. 


The following C program (figure 4-3) calls the NOS/VE Math Library SIND function to 
compute a full sine wave. 


The SIND function uses call-by-reference, which means the function expects an address. 
Since this program is calling the Math Library and not a specific C function, the SIND 
function expects left-justified addresses. This program uses the left-bit-shift (<<) 
operator to left-justify the addresses. 


/* This C program uses the SIND function to compute a full sine wave. 
a7 


#define MAX_DEGREES 360 


main() 
{ 


int count = 0, /* loop counter 
address_deg; /* left-justified address of the degree 


float degree, /* 0 to 360 degrees 
sin_of_degree, /* Sine of degree 
SIND(); /* declaration of the Math Library function 
/* declaration must be capitalized 


for (count=1; count <= MAX_DEGREES; ++count) 
{ 


Get the address of DEGREE. Then use the left bit-shift operator (<<) 
to left justify the address 16 bits. This is necessary because C 
uses a 48-bit right-justified pointer and NOS/VE expects left-justified 
addresses. 

degree = count; 


address_deg = (int) &degree << 16; 


sin_of_degree = SIND(address_deg) ; 


printf("The sine of %3.0f is %f.\n", degree, sin_of_degree) ; 


} /* end for loop */ 


Figure 4-3. C Program Calling the Math Library Using Call-by-Reference 
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Figure 4-4 illustrates how to call the Math Library using call-by-value. The C #define 
statement declares VMOD as a call-by-value routine. The call-by-reference Math 
Library function name is also illustrated. 


NOTE 
A Math Library function call from C must be capitalized. 


/* This C program names VMOD as an alias to the call-by-value entry point 
of MLP$VMOD. 
“7 
#define VMOD MLP$VMOD 
main() 
{ 
int i 83; 
int j 8; 
int k; 


printf (" The size of short int is “#d\n", sizeof(short int)); 


printf (" The size of int is %d\n ", sizeof(int)); 
printf (" The size of long int is %d\n ", sizeof(long int)); 
Call MOD by reference. 


k = MOD((int)(&i)<<16,(int) (&j)<<16); 
printf (" The modulus of %d\n is", k); 
Call MOD by value. 


k = VMOD (i, 3); 
printf (" The Mod of %d\n is", k); 
exit (0); 


Figure 4-4. C Program Calling the Math Library Using Call-by-Value 
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CYBIL Calling the Math Library 


CYBIL can call the Math Library with either a call-by-reference or a call-by-value 
entry point. Double precision functions can only be called with call-by-reference entry 


points. 


NOTE 
CYBIL parameters to Math Library routines must be VAR parameters. 


The following example (figure 4-5) illustrates a call-by-reference hyperbolic sine (SINH) 
function. 


MODULE math_example; 
{ The following "*copyc" can be expanded by the following command: 


{ EXPAND_SOURCE_FILE .. 
{ file ALTERNATE_BASE=$SYSTEM. COMMON .PSF$EXTERNAL_INTERFACE_SOURCE 


*copyc mip$rsinh 


FUNCTION hyperbolic_sine ( 
VAR x: real ): real; 


{ Parameters to Math Library routines are VAR parameters 


hyperbolic_sine := mip$rsinh ( x ); 


FUNCEND hyperbolic_sine; 


MODEND math_example; 


Figure 4-5. CYBIL Program Calling the Math Library Using Call-by-Reference 
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CYBIL programs can call complex numbers only if they are defined as type 
MLT$COMPLEX. Figure 4-6 illustrates how to call a complex function from CYBIL. 


MODULE cmm1l_complex_example; 
*copyc mip$rccos 


This module shows how to handle complex numbers in CYBIL. 
Complex numbers are defined as type MLT$COMPLEX, which is 

a two-word record. CYBIL will not accept functions which 
return a record. Hence, the complex functions are defined 

as returning longreal. To convert a lJongreal to an mit$complex, 
use the CYBIL intrinsic #UNCHECKED_CONVERSION. This example 
calls the complex cosine routine. 


PROCEDURE complex_cosine 
(VAR z_in: mlt$complex; 
VAR z_out: mlt$complex); 


VAR 
d: longreal; 


d := mip$rccos (z_in); 
#UNCHECKED_CONVERSION (d, z_out); 


PROCEND complex_cosine; 


PROGRAM example; 


A FORTRAN program to print a complex value using FORTRAN I/O 


PROCEDURE [XREF] complex_print 
(VAR value: mlt$complex); 


result: mit$complex; 


z.real_ := 3.4; 
z.imag := -2.1; 
complex_cosine (z, result); 
complex_print (result); 
PROCEND example; 
MODEND cmm1_complex_example; 


Figure 4-6. CYBIL Program Calling Complex Function CCOS Using 
MLT$COMPLEX 
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Figure 4-7 illustrates the FORTRAN program COMPLEX_PRINT which prints the 
complex result to the screen. 


SUBROUTINE complex_print (value) 


COMPLEX value 
PRINT *, value 
END 


Figure 4-7. FORTRAN Program COMPLEX _ PRINT 


Figure 4-8 illustrates the NOS/VE commands needed to expand the source file and run 
the CYBIL and FORTRAN object code in order to print the CCOS result. 


/expand_source_file $user.cmm]_complex_example .. 
../alternate_base=$system.psf$external_interface_source 


/cybil compile b=cybil_binary 
/fortran $user .complex_print b=fortran_binary 
/execute_task (cybil_binary fortran_binary) 


Figure 4-8. NOS/VE Commands To Run CYBIL and FORTRAN Object Code 


Figure 4-9 illustrates the output from this program. 


(-4 .0067 14482636, -1.027749704085) 


Figure 4-9. CYBIL CCOS Output 
For Better Performance 
The Afterburner can eliminate call and return instructions and improve execution time. 


The AFTERBURN_OBJECT_TEXT command optimizes FORTRAN and CYBIL 
programs by inlining subprograms. Inlining a subprogram places the subprogram 
statements where they are called, thus eliminating call and return instructions. This 
reduces the overhead associated with passing parameters, saving registers, and 
branching to and from the subprogram. See the section Improving Execution Time in 
the NOS/VE Object Code Management manual for additional information. 
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FORTRAN Version 1 Calling the Math Library 


FORTRAN Version 1 supports calls to the Math Library and provides several 
language-specific intrinsic functions. 


A FORTRAN Version 1 intrinsic function is a compiler-defined procedure that returns 
a single value. Intrinsic functions are referenced in the same way as user-written 
(external) function subprograms. If, in a particular program unit, a variable, array, or 
statement function is declared with the same name as an intrinsic function, the name 
cannot refer to the intrinsic function within that program unit. If a function 
subprogram is written with the same name as an intrinsic function, use of the name 
references the intrinsic function, unless the name is declared as the name of an 
external function with the EXTERNAL statement. (This is described in chapter 3 of 
the FORTRAN Version 1 for NOS/VE Language Definition manual.) 


Intrinsic functions are typed by default and need not appear in any explicit type 
statement in the program. Explicitly typing a generic intrinsic function name does not 
remove the generic properties of the name. If you attempt to type an intrinsic function 
as something other than its default type, a warning message is displayed and the type 
statement is disregarded. 


A function accepting integer, byte, real, complex, or double precision type arguments 
also accepts boolean arguments. A boolean argument is converted to integer, if integer 
is an allowable argument type, or to real, if real is an allowable argument type; 
otherwise, it is converted to double precision or complex, before computation. An 
IMPLICIT NONE statement does not affect the type of the results of any intrinsic 
functions. 


Inlined Functions 
The following functions are available for inlining by the FORTRAN Version 1 compiler: 


ACOS 
ALOG 
ALOG10 
ASIN 
ATAN 
COS 
EXP 
SIN 
SQRT 
TAN 
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FORTRAN Version 1 Uses Call-by-Value or Call-by-Reference 


Most of the FORTRAN Version 1 intrinsic functions are in the Math Library and are 
accessed through the call-by-value routine. FORTRAN Version 1 calls Math Library 
functions with call-by-value unless call-by-reference is explicitly declared. To access an 
intrinsic function through the call-by-reference calling procedure, specify 
EXPRESSION._EVALUATION =REFERENCE (EE=R) on the FORTRAN command. 


If an execution error occurs, the use of call-by-reference causes internal FORTRAN 
routines to generate descriptive error messages. If call-by-reference is not selected, the 
operating system produces error messages which generally provide less information. 


NOTE 


Always use normalized standard floating-point form for real, double precision, and 
complex arguments to intrinsic functions; unnormalized or nonstandard arguments can 
cause undefined results. FORTRAN automatically normalizes all real, double precision, 
and complex constants. Results of all floating-point operations (with standard 
normalized or zero operands) are normalized or zero. However, it is possible to 
generate unnormalized or nonstandard operands by means of boolean expressions, 
equivalencing, or various input operations. 


The FORTRAN Version 1 intrinsic functions are summarized in table 4-3 (FORTRAN 
Version 2, as discussed in the following section, supports the same functions as well as 
a set of array-processing functions.) The functions are listed in alphabetical order by 
generic name or, where no generic name exists, by specific name. An asterisk in the 
Generic Name column indicates that the function is a Control Data extension. For 
specific names, the types of the arguments and results are shown. Boolean arguments 
are not listed in the table, but follow the conversion rules described above. Integer 
denotes 8-byte integer. Real denotes 8-byte real. Double precision denotes 16-byte real. 
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Table 4-3. FORTRAN Intrinsic Functions 


Generic Specific Type of Type of 
Name Names Argument Function Description 
ABS IABS Integer (2-byte) Integer Absolute value 
Integer (4-byte) Integer 
Integer Integer 
. Byte Integer 
ABS Real Real 
DABS Double Double 
CABS Complex Real 
ACOS ACOS Real Real Arccosine 
DACOS Double Double 
None AIMAG Complex Real Imaginary part of complex 
argument 
AINT AINT Real Real Truncation 
DINT Double Double 
None AMAX0 Integer Real Maximum value 
None AMINO Integer Real Minimum value 
None AND Any type but Boolean Boolean product 
character 
ANINT ANINT Real Real Nearest whole number 
DNINT Double Double 
ASIN ASIN Real Real Arcsine 
DASIN Double Double 
ATAN ATAN Real Real Arctangent 
DATAN Double Double 
ATAN2 ATAN2 Real Real Arctangent (two arguments) 
DATAN2 Double Double 
None* ATANH Real Real Hyperbolic arctangent 
BOOL* —_ Any type but Boolean Conversion to boolean 
logical 
None CHAR Integer (2-byte) Character Integer conversion to 
Integer (4-byte) Character character 
Integer Character 
Byte Character 
None* COMPL Any type but Boolean Complement 
character 


Integer denotes full word (8-byte) integers. An asterisk indicates a Control Data 
extension. 


(Continued) 
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Table 4-3. FORTRAN Intrinsic Functions (Continued) 


Generic 
Name 


None* 


CMPLX 


COs 


None* 


COSH 


None 


DBLE 


DIM 


None 


None* 


None* 


None* 


Specific 
Names 


COTAN 


_. ERF 


ERFC 


Type of 
Argument 


Real 


Integer (2-byte) 
Integer (4-byte) 
Integer 

Byte 

Real 

Double 
Complex 


Real 
Double 
Complex 


Real 


Real 
Double 


Complex 


Integer (2-byte) 
Integer (4-byte) 
Integer 

Byte 

Real 

Double 
Complex 


Integer (2-byte) 
Integer (4-byte) 
Integer 

Byte 

Real 

Double 


_ Real 


Any type but 
character 


Real 


~ Real 
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Type of 
Function 


Real 


Complex 
Complex 
Complex 
Complex 
Complex 
Complex 
Complex 


Real 
Double 
Complex 


Real 


Real 
Double 


Complex 


Double 
Double 
Double 
Double 
Double 
Double 
Double 


Integer 
Integer 
Integer 
Integer 
Real 

Double 


Double 


Boolean 


Real 
Real 


Description 


Cotangent (argument in 
radians) 


Conversion to complex 


Cosine, argument 
in radians 
Cosine, argument in degrees 


Hyperbolic cosine 


Negation of imaginary part 


Conversion to double 
precision 


Positive difference 


Double precision product 


Equivalence 


Error function © 


Complementary error 
function. 


Integer denotes full word (8-byte) integers. An asterisk indicates a Control Data 


extension. 
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Table 4-3. FORTRAN Intrinsic Functions (Continued) 


Generic Specific Type of Type of 
Name Names Argument Function Description 
EXP EXP Real Real Exponential function 
DEXP Double Double 
CEXP Complex Complex 
EXTB None al: Any type but Boolean Extract a string of bits 
character a2,a3: 
Integer 
None ICHAR Character Integer Character conversion to 
integer 
None INDEX Character Integer Index of a substring 
INSB None al,a4: Any type - Boolean Insert a string of bits 
but character 
a2,a3: Integer 
INT INT Integer (2-byte) Integer Conversion to integer 
Integer (4-byte) Integer 
Integer Integer 
Byte Integer 
INT Real » Integer 
IFIX Real Integer 
IDINT Double Integer 
— Complex Integer 
None LEN Character Integer Length of character string 
None LGE Character Logical Lexically greater than or 
equal 
None LGT Character Logical - Lexically greater than 
None LLE Character Logical Lexically less than or equal 
None LLT Character Logical Lexically less than 
LOG ALOG Real Real Natural logarithm 
DLOG Double Double 
CLOG Complex -° + Complex 
LOG10 ALOG10 Real Real ~ Common logarithm 
DLOGI10::. Double Double 
None* MASK Integer or Boolean Mask 
Boolean 


Integer denotes full word (8-byte) integers. An asterisk indicates a Control Data 
extension. 


(Continued) 
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Table 4-3. 


Generic 
Name 


MAX 


None 


MIN 


None 


MOD 


None* 


NINT 


None* 


PTR* 


None* 


FORTRAN Intrinsic Functions (Continued) 


Specific 
Names 


MAX0 


RANF 


Type of 
Argument 


Integer (2-byte) 
Integer (4-byte) 
Integer 
Byte 

Real 

Double 


Real 


Integer (2-byte) 
Integer (4-byte) 
Integer 

Byte 

Real 

Double 


Real 


Integer (2-byte) 
Integer (4-byte) 
Integer 

Byte — 

Real 

Double 


Any type but: 
character 


Real 
Double 


Any type but 
character 


Any type 


None 
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Type of 
Function 


Integer 
Integer 
Integer 
Integer 
Real 

Double 


Integer 


Integer 
Integer 
Integer 
Integer 
Real 

Double 


Integer 


Integer 
Integer 
Integer 
Integer 
Real 

Double 


Boolean 
Integer 
Integer 


Boolean 


Boolean 


Real 


Description 


Largest value 


Largest value 


Smallest value 


Smallest value 


Remaindering 


Nonequivalence 
Nearest integer 
Boolean sum 


Parameter address; used only 
when passing parameters to 
C or CYBIL routines 


Random number generator 


Integer denotes full word (8-byte) integers. An asterisk indicates a Control Data 


extension. 
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Table 4-3. FORTRAN Intrinsic Functions (Continued) 


Generic Specific Type of Type of \ 
Name Names Argument Function Description 
REAL FLOAT Integer (2-byte) Real Conversion to real 
Integer (4-byte) Real 
Integer Real 
Byte Real 
REAL Integer Real 
Real Real 
Complex Real 
SNGL - Double Real 
None* SHIFT Any type but Boolean Shift 


character for al; 
integer or Boolean 


for a2 
SIGN ISIGN Integer (2-byte) Integer Transfer of sign 
Integer (4-byte) Integer 
Integer Integer 
Byte Integer 
SIGN Real Real 
DSIGN Double Double 
SIN SIN Real | Real Sine (argument in radians) 
DSIN Double Double 
CSIN Complex Complex 
None* SIND Real Real Sine (argument in degrees) 
SINH SINH Real Real Hyperbolic sine 
DSINH Double Double 
SQRT SQRT Real Real Square root 
DSQRT Double Double 
CSQRT Complex Complex 
SUMI1S _ Integer Integer Sum of 1 bits that are set 
Real Integer in a word 
Double Integer 
Complex Integer 
TAN TAN Real Real Tangent (argument in 
DTAN Double Double radians) 
None* TAND Real Real Tangent (argument in 
degrees) 
TANH TANH Real Real Hyperbolic tangent 
DTANH Double Double 
None* XOR Any type but Boolean Exclusive OR 
character 


Integer denotes full word (8-byte) integers. An asterisk indicates a Control Data 
extension. 
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Table 6-2 (in chapter 6) shows the domain and range for a subset of the Math Library 
functions. 


For Better Performance 


The Afterburner can eliminate call and return instructions and improve execution time. 


The AFTERBURN_OBJECT_TEXT command optimizes FORTRAN and CYBIL 
programs by inlining subprograms. Inlining a subprogram places the subprogram 
statements where they are called, thus eliminating call and return instructions. This 
reduces the overhead associated with passing parameters, saving registers, and 
branching to and from the subprogram. See Improving Execution Time in the NOS/VE 
Object Code Management manual for additional information. 
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FORTRAN Version 2 Calling the Math Library 


FORTRAN Version 2 supports calls to the Math Library and provides the same 
language-specific intrinsic functions as FORTRAN Version 1. FORTRAN Version 2 also 
provides several array-processing functions in addition to the functions handled by the 
Math Library. FORTRAN Version 2 arguments can be array-valued. 


Inlined Functions 


The following functions are available for inlining by the FORTRAN Version 2 compiler: 


ACOS 
ALOG 
ALOG10 
ASIN 
ATAN 
COS 
EXP 
SIN 
SQRT 
TAN 


The primary Math Library interface difference between FORTRAN Version 1 and 
FORTRAN Version 2 is that the arguments can be array-valued and the programs can 
be vectorized. Refer to chapter 7, Vector Processing, for a discussion of array-valued 
arguments. 


For Better Performance 


The Afterburner can eliminate call and return instructions and improve execution time. 


The AFTERBURN_OBJECT_TEXT command optimizes FORTRAN and CYBIL 
programs by inlining subprograms. Inlining a subprogram places the subprogram 
statements where they are called, thus eliminating call and return instructions. This 
reduces the overhead associated with passing parameters, saving registers, and 
branching to and from the subprogram. See Improving Execution Time in the NOS/VE 
Object Code Management manual for additional information. 
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Table 4-4 lists the FORTRAN Version 1 and FORTRAN Version 2 intrinsic functions. 
For multiple-argument functions, al indicates argument 1, a2 indicates argument 2, 
and so forth. The generic and specific names are listed in alphabetical order. See the 
FORTRAN Version 1 or FORTRAN Version 2 manual for complete descriptions. 


Table 4-4. FORTRAN Function Summary 


Name 


ABS 
ACOS 
AIMAG 
AINT 


ALL 


ALLOCATED 


ALOG 
ALOGI0 


AMAX0 
AMAX]1 
AMINO 
AMIN1 


AMOD 


AND 
ANINT 
ANY 


ASIN 
ATAN 
ATANH 
ATAN2 


BOOL 


CABS 
CCOS 
CEXP 


CHAR 
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Source 


Math Library 
Math Library 
Math Library 
Math Library 


FORTRAN Version 2 


FORTRAN Version 2 


Math Library 
Math Library 


FORTRAN Versions 1 and 2 
FORTRAN Versions 1 and 2 
FORTRAN Versions 1 and 2 
FORTRAN Versions 1 and 2 


Math Library 


FORTRAN Versions 1 and 2 
Math Library 
FORTRAN Version 2 


Math Library 
Math Library 
Math Library 
Math Library 


FORTRAN Versions 1 and 2 


Math Library 
Math Library 
Math Library 


- FORTRAN Versions 1 and 2 


FORTRAN Function Summary 


Description 


Absolute value 

Arccosine 

Imaginary part of complex argument 
Truncation 


True if every element of al, along 
the optional dimension specification 
a2, has the logical value true 


Scalar logical value indicating 
whether or not an allocatable array 
is allocated 


Natural logarithm 
Common logarithm (base 10) 


Maximum value 
Largest value 
Minimum value 
Smallest value 


Remainder of a ratio (uses real 
numbers) 


Boolean product 
Nearest whole number 


Logical value true is one or more 
elements of al, along the optional 
dimension specification a2, has the 
logical value true 


Arcsine 

Arctangent 

Hyperbolic arctangent 
Arctangent (two arguments) 


Conversion to boolean 


Absolute value 
Cosine, argument in radians 
Exponential function 


Integer conversion to character 
(Continued) 
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Table 4-4. FORTRAN Function Summary (Continued) 


Name 


CLOG 


CMPLX 
COMPL 


CONJG 
COs 
COSD 
OSH 
COTAN 


COUNT 


CSIN 
CSQRT 
DABS 
DACOS 


DASIN 
DATAN 
DATAN2 


DBLE 


DCOS 
DCOSH 
DDIM 
DEXP 


DIM 
DINT 
DLOG 
DLOGI10 


DMAX1 
DMINI1 


DMOD 


DNINT 
DOTPRODUCT 


DPROD 
DSIGN 
DSIN 
DSINH 
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Source 


Math Library 


FORTRAN Versions 1 and 2 
FORTRAN Versions 1 and 2 


Math Library 
Math Library 
Math Library 
Math Library 
Math Library 


FORTRAN Version 2 


Math Library 
Math Library 
Math Library 
Math Library 


Math Library 
Math Library 
Math Library 


FORTRAN Versions 1 and 2 


Math Library 
Math Library 
Math Library 
Math Library 


Math Library 
Math Library 
Math Library 


- Math Library 


FORTRAN Versions 1 and 2 
FORTRAN Versions 1 and 2 


Math Library 


Math Library 


FORTRAN Version 2 


Math Library 
Math Library 
Math Library 
Math Library 


Description 


Natural logarithm 


Conversion to complex 
Complement 


Negation of imaginary part 
Cosine, argument in radians 
Cosine, argument in degrees 
Hyperbolic cosine 

Cotangent (argument in radians) 


Number of true elements in al along 
the optional dimension specification 
a2 


Sine (argument in radians) 
Square root 

Absolute value 

Arccosine 


Arcsine 
Arctangent 
Arctangent (two arguments) 


Conversion to double precision 


Cosine, argument in radians 
Hyperbolic cosine 

Positive difference 
Exponential function 


Positive difference 
Truncation 

Natural logarithm 
Common logarithm 


Largest value 
Smallest value 


Remainder of a ratio (uses double 
precision numbers) 
Nearest whole number 


Dot product of al and a2 


Double precision product 
Transfer of sign 

Sine (argument in radians) 
Hyperbolic sine 


(Continued) 
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Table 4-4. FORTRAN Function Summary (Continued) 


Name 


DSQRT 
DTAN 
DTANH 
EQV 
FLOAT 


ERF 
ERFC 
EXP 
EXTB 
IABS 


ICHAR 
IDIM 
IDINT 
IDNINT 


IFIX 
INDEX 


INSB 
INT 
ISIGN 
LBOUND 


LEN 
LGE 
LGT 
LLE 


LLT 
LOG 
LOG10 
MASK 


MATMUL 
MAX 
MAXVAL 
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Source 


Math Library 
Math Library 
Math Library 


FORTRAN 
FORTRAN 


Versions 1 


Versions 1 


Math Library 
Math Library 
Math Library 
Math Library 
Math Library 


FORTRAN 


FORTRAN 


Versions 1 


- .Math Library 


Versions 1 


Math Library 


FORTRAN 
FORTRAN 


Versions 1 
Versions 1 


Math Library 


FORTRAN 


Versions 1 


Math Library 


FORTRAN 


FORTRAN 
FORTRAN 
FORTRAN 
FORTRAN 


FORTRAN 
FORTRAN 
FORTRAN 
FORTRAN 


FORTRAN 


' FORTRAN 


FORTRAN 


Version 2 


Versions 1 
Versions 1 
Versions 1 
Versions 1 


Versions 
Versions 


1 
1 
Versions 1 
Versions 1 


Version 2 
Versions 1 


Version 2 


and 2 


and 2 


and 2 


and 2 


and 2 
and 2 


and 2 


and 2 
and 2 
and 2 
and 2 


and 2 
and 2 
and 2 
and 2 


and 2 


Description 


Square root 
Tangent (argument in radians) 
Hyperbolic tangent 


Equivalence 
Conversion to real 


Error function 
Complementary error function 
Exponential function 

Extract a string of bits 
Absolute value 


Character conversion to integer 
Positive difference 

Conversion to integer 

Nearest integer 


Conversion to integer 
Index of a substring 


Insert a string of bits 

Conversion to integer 

Transfer of sign 

Lower bound of dimension a2 of al 


Length of character string 
Lexically greater than or equal 
Lexically greater than 
Lexically less than or equal 


Lexically less than 
Natural logarithm 
Common logarithm 
Boolean result 


Product of arguments al and a2 
Largest value 


Maximum element of al along 
dimension a2 corresponding to true 
elements of a3 


(Continued) 
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FORTRAN Function Summary 


Table 4-4. FORTRAN Function Summary (Continued) 


Name Source Description 

MAX0 FORTRAN Versions 1 and 2 Largest value 

MAX1 FORTRAN Versions 1 and 2 Largest value 

MERGE FORTRAN Version 2 Result containing the values of al 


corresponding to true elements of a3, 
and the values of a2 corresponding to 
false elements of a3 


MIN FORTRAN Versions 1 and 2 Smallest value 


MIN VAL FORTRAN Version 2 Minimum element of al along 
dimension a2 corresponding to true 
elements of a3 


‘“MINO FORTRAN Versions 1 and 2 Smallest value 

MINI FORTRAN Versions 1 and 2 Smallest value 

MOD Math Library Remainder of a ratio 

NEQV FORTRAN Versions 1 and 2 Nonequivalence 

NINT Math Library Nearest integer 

OR FORTRAN Versions 1 and 2 Boolean sum 

PACK FORTRAN Version 2 One-dimensional array consisting of 


all elements of al corresponding to 
true elements of a2 


PRODUCT FORTRAN Version 2 Product of elements in argument al 
along dimension a2 corresponding to 
.TRUE. elements of a3 


PTR FORTRAN Versions 1 and 2. Parameter address; used only when 
passing parameters to C or CYBIL 
routines 

RANF Math Library Random number generator 

RANK FORTRAN Version 2 Number of dimensions in al 

REAL FORTRAN Versions 1 and 2 Conversion to real 

SEQ FORTRAN Version 2 Returns a one-dimensional array 

SHIFT FORTRAN Versions 1 and 2 Shift 

(Continued) 
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Table 4-4. FORTRAN Function Summary (Continued) 


Name 


SIGN 
SIN 

SIND 
SINH 


SIZE 
SNGL 
SQRT 
SUM 


SUMIS 
TAN 
TAND 
TANH 


UNBOUND 
UNPACK 


XOR 
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Source 


Math Library 
Math Library 
Math Library 
Math Library 


FORTRAN Version 2 
FORTRAN Versions 1 and 2 
Math Library 

FORTRAN Version 2 


Math Library 
Math Library 
Math Library 
Math Library 


FORTRAN Version 2 
FORTRAN Version 2 


FORTRAN Versions 1 and 2 


Description 


Transfer of sign 

Sine (argument in radians) 
Sine (argument in (degrees) 
Hyperbolic sine 


Size of an array 
Conversion to real 
Square root 


Sum of elements in argument al 
along dimension a2 corresponding to 
-TRUE. elements in a3 


Sum of 1 bits that are set in a word 
Tangent (argument in radians) 
Tangent (argument in degrees) 
Hyperbolic tangent 


Upper bound of dimension a2 of al 
Array with the same shape as a3 
and the same type as al 


Exclusive OR 
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Pascal Calling the Math Library 


Pascal Calling the Math Library 


The Pascal compiler provides a transparent interface to several Math Library functions. 
The language also provides several predefined functions. Pascal makes no distinction 
between Math Library functions and predefined functions. In some cases Pascal uses a 
different name for a function actually provided by the Math Library (for example, the 
Pascal ARCTAN, ARCTAN2, and ARCTANH are different names for the Math Library 
functions ATAN, ATAN2, and ATANH, respectively). 


The following functions are available to the Pascal programmer: 


ABS COTAN POWER 
ACOS DIM RANF 
AMOD ERF SIGN 
ANINT -ERFC SIN 
ARCTAN EXP SINH 
ARCTAN2 IDIM SQR 
ARCTANH ISIGN SQRT 
ASIN LN TAN 
Cos LN10 TANH 
COSH NINT 


The Pascal function POWER combines the Math Library functions ITOI, ITOX, XTOI, 
and XTOX. POWER accepts integer or real arguments. 


In NOS/VE Pascal, most math functions are called from the Math Library, except ABS 
and SQR are implemented directly by Pascal generated code. All Pascal function calls 
are transparent to the user. 


Inlined Functions 


At the user’s option, the Pascal compiler generates inline code structures for the 
following functions: 


ACOS 

LN (ALOG) 

LN (ALOG10) 
ASIN 

ARCTAN (ATAN) 
Cos 

EXP 

SIN 

SQRT 

TAN 


Pascal Calling Routines 


When you call Pascal functions, the compile time of your program is affected by the 
EXPRESSION_EVALUATION parameter on the PASCAL command. If you specify 
EXPRESSION_EVALUATION = REFERENCE, the compiler selects call-by-reference, | 
which does more argument checking and may be slower. The default is EXPRESSION_ 
EVALUATION =NONE, where the compiler selects call-by-value, which does less 
argument checking. 
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Pascal Math Function Attributes 


Pascal Calling the Math Library 


Table 4-5 lists the domain and range for applicable Pascal math functions. 


Table 4-5. Mathematical Intrinsic Functions 


Function 


ACOS(a) 


ARCTAN(a) 
ARCTAN2(al1,a2) 


ARCTANH(a) 


ASIN (a) 
COS(a) 
COSH(a) 
COTAN(a) 
ERF(a) 
ERFC(a) 
EXP(a) 
LN(a) 
LN10(a) 
SIN(a) 
SINH(a) 
SQRT(a) 
TAN(a) 
TANH(a) 
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Domain 

la|=1 

-infinity =a =infinity 
a2<0, al<0 

a2<0, al=0 

a2=0, al<0 

a2=0, al>0 

a2>0, al<0 

a2>0, al=0 

a2=0, al=0O (error) 
jal=1 

|a|=1 

|a| <2**47 
la|<4095*log(2) 

lal <2**47 
~infinity =a =infinity 
~infinity =a =25.923 
a<4095*LOG(2) 
a>0. 

a>0 

lal <2**47 

lal <4095*log(2) 

a=0 

lal <2**47 


All valid real quantities 


Range 

0=ACOS(a)= pi 
—pi/2=ARCTAN(a) =pi/2 
-pi< ARCTAN2(al,a2) <—pi/2 
pi/2=ARCTAN2(al,a2) =pi 
ARCTAN2(al,a2) =—pi/2 
ARCTAN2(al,a2) = pi/2 
-pi/2<ARCTAN2(al,a2) <0 
0=ARCTAN2(al,a2) <pi/2 
All valid real quantities 
-pi/2 = ASIN(a) = pi/2 
-~1=COS(a)=1 

COSH(a)=1 

All valid real quantities 
-1=ERF(a)=1 

0=ERFC(a) =2 

All valid real quantities 
|LN(a)|<4095*LN(a) 
[LN10(a)|<4095*LN(2) base 10 
-1=SIN(a)=1 

All valid real quantities 
SQRT(a)=0 | 
All valid real quantities 


-1=TANH(a)=1 
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Error Handling D 


This chapter discusses two different kinds of errors: 
e Processing errors (algorithm error and machine round-off error) 
e Input errors (arguments that are out of range) 


This chapter also discusses accuracy measurement and NOS/VE condition handling. 
Understanding how the Math Library handles errors and how the NOS/VE operating 
system handles conditions may improve your ability to use the Math Library as a 
resource. 


NOTE 


This chapter discusses Math Library error handling in general. See chapter 7, Vector 
Processing, for additional information on vector error handling. 
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Processing Error 


Processing Error 
Processing error is defined as the computed value of a function minus the true value. 


A certain amount of processing error occurs during the compuration of the Math 
Library functions, and is composed of two parts: 


e Algorithm error 


@® Machine round-off error 


Algorithm Error 


Algorithm error is caused by inaccuracies inherent in the mathematical process used to 
compute the result. It includes error in coefficients used in the algorithm. 


A curve representing the algorithm error is usually smooth with discontinuities at 

breaks in the range reduction technique. Error in the coefficients that are involved in 

range reduction can also occur. Usually, a good algorithm which uses good coefficients \ 
will not have an error greater than one-half in the last bit of the result. 


Machine Round-Off Error 


Machine round-off error is caused by the finite nature of the computer. Because only a 
finite number of bits can be represented in each word of memory, some precision is 
lost. 


Round-off error is difficult to predict or graph. A graph of round-off error is extremely 4 
discontinuous, but maximum and minimum error over small intervals can be shown. 
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Input Error 


Input Error 


Input error is handled differently by the call-by-reference and call-by-value routines. 
Error handling takes place when the argument or result is outside the range of the 
function. 


If you are accessing the Math Library from a language other than FORTRAN, you can 
establish a condition handler to be used in conjunction with the error handling 
mechanism under the call-by-reference routine. The Math Library automatically 
establishes this condition handler for FORTRAN programs. 


Call-By-Reference Error Handling 


When the argument or result is out-of-range in a call-by-reference routine, an error 
message is displayed and the corresponding default error value is placed in the result 
registers XE and XF. Figure 5-1 is a Nassi-Shneiderman chart! illustrating the logical 
flow of call-by-reference error handling. 


Call-By-Value Error Handling 


If the call-by-value routine is called directly, that is, if the call-by-reference routine is 
not called, the job aborts if either of the following situations occurs: 


© An out-of-range argument is passed to the call-by-value routine. 
© The result of the computation in a call-by-value routine is out-of-range. 


The call-by-value routine does not guarantee any other type of error handling, and the 
values in registers XE and XF are undefined unless otherwise specified. 


1. Nassi-Shneiderman charts (also called Chapin charts) are read like flow charts: a rectangle indicates a 
process, an inverted isosceles triangle indicates a decision, and a right triangle indicates a branch from a 
decision. 


60486513 H Error Handling 5-3 


Input Error 


Call-by-Reference Argument List 


wa Stored in Register A4 lle | 
Abnormal status set 
Entry Point in global variable 
MLV$STATUS (of type OST$STATUS) 
Call-by-Value Register XE Register XE 
Routine Register XF 


Register A4 
Algorithm ' ‘ 
Pointer to parameter list 


Computation Register XD 
Number of parameters (1 or 2) 


Cleared of all arithmetic errors 
Return Ungated routine . 

MLP$ERROR_PROCESSOR is called 
All registers are saved in the save 
area 
MLP$ERROR_PROCESSOR calls 
PMP$CAUSE_CONDITION with user 
condition MATH_LIBRARY_ERROR 
Pointer is set to the previous save 
area (the registers saved by the call- — 
by-reference routine) 

Status returned MLV$STATUS 

from PMP$CAUSE_ 

CONDITION 


Figure 5-1. Logical Flow of Call-by-Reference Error Handling 
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Accuracy Measurements 


When performance improvements are made to Math Library functions, the following 
accuracy measurements are calculated: 


@ Relative error 
@ Root mean square relative error 


The Taylor series of a Math Library function is sometimes used in the calculation of 
relative error and root mean square relative error. For a discussion of Taylor series, 
refer to any calculus text (for example, Calculus and Analytic Geometry by G. B. 
Thomas). The following paragraphs discuss these accuracy measurements. 


Relative Error 


Relative error is the processing error divided by the true value. The magnitude of 
relative error can be analyzed in two ways: 


@ Using the relative error formula 


@ Examining bit error 


Using the Relative Error Formula 
Relative error can be calculated by using the following formula: 
‘Relative Error = (Function Value - Exact Value) / Exact Value 


This method is used for single precision algorithms accurate to less than 2E-15, and 
round-off errors less than 10E-15. 


Changing the last bit in a single precision number produces a relative change between 
3.5E-15 for a large mantissa and 7.1E-15 for a small but normalized mantissa. This 
method is used for the error analysis of the Math Library functions. 


Examining Bit Error 


The second method of analyzing relative error is finding out how omany bits the routine 
differs from the exact value. This is called bit error. 


To determine how many bits off a routine is, a function is evaluated in double 
precision and rounded to single precision. Then, assuming the exponents are the same, 
the mantissas are subtracted and the integer difference is the bit error. 


Root Mean Square Relative Error 


-Root mean square error is the square root of the average of the squares of the relative 
errors of all the arguments. 
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NOS/VE Condition Handler 


Under call-by-reference, the Math Library generates the special software condition 
MATH LIBRARY_ERROR. The language under which you are executing ordinarily 
handles the processing of this condition. If no condition handler for MATH. LIBRARY_ 
ERROR has been established, NOS/VE handles the processing of this condition. 


You can also write your own condition handler. NOS/VE provides two mechanisms for 
specifying the action to be taken when an abnormal condition occurs: 


e Error processing 


® Condition handling 


Error Processing 


Error processing is available when the STATUS parameter is included in a NOS/VE 
command and the command terminates with an abnormal status. 


All NOS/VE commands have an optional parameter called STATUS. When you specify 
the STATUS parameter, you must supply a previously declared variable of type 
STATUS as its value. This variable is used by the System Command Language (SCL) 
interpreter to hold the completion status of the command. 


If you include the STATUS parameter on a command, the SCL interpreter proceeds to 
the next command even if an abnormal condition is encountered. Most commands do 
not inform you of an error if you include the STATUS parameter, but succeeding 
commands may check the contents of the status variable and alter the flow of 
statements based on abnormal conditions. 


If you do not include a value for the STATUS parameter and an error occurs, the SCL 
interpreter skips succeeding commands in the current input block as described in the 
NOS/VE System Usage manual. 


Condition Handling 


When you specify the STATUS parameter on a command, you can alter the command 
stream based on the completion status of the command. You can also provide condition 
handlers to alter the command stream in the event of certain system conditions. 


Condition handling is activated when a condition exists for a command.that does not 
contain a STATUS parameter, or is beyond the scope of STATUS variable error 
processing. When condition handling is activated, your batch or interactive job is 
usually terminated. If you receive a condition handling error, see the NOS/VE 
Diagnostic Messages manual for a description of the error and a recommended action. 


The following information defines the interface between the Math Library and the 
operating system, whether or not a condition handler has been established. For detailed 
information on the procedures used in establishing a user-defined condition handler, see 
the NOS/VE System Usage manual. 
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NOS/VE Condition Handler 


When an error occurs in a Math Library function under a call-by-reference routine, the 
following events occur: 


1. 


An appropriate abnormal status is set into global variable MLV$STATUS (of type 
OST$STATUS). 


The appropriate default error value is placed in the result register(s) XE and/or XF. 
Register A4 contains the pointer to the parameter list passed to the 
call-by-reference routine. Register XD contains the number of parameters for the 
call-by-reference routine. For example, register XD will contain a 1 for the 
call-by-reference routine MLP$RSIN, and a 2 for MLP$RZTOZ. The User Condition 
Register is cleared of all arithmetic errors. 


Ungated routine MLP$ERROR_PROCESSOR is called with all registers saved in 
the save area so that they can be accessed by a condition handler. 


MLP$ERROR_PROCESSOR calls the PMP$CAUSE_CONDITION procedure with 
user condition MATH_LIBRARY_ERROR and a pointer to the previous save area 
(the registers saved by the call-by-reference routine) as the condition descriptor. 


Upon return from the PMP$CAUSE_CONDITION procedure, MLP$ERROR_ 
PROCESSOR is exited if the returned status is normal. If the return status is not 
normal, the PMP$ABORT procedure is called with one of two conditions: 


e If no established condition handler exists for MATH _LIBRARY._ERROR, then 
status MLV$STATUS is used. 


e If an established condition handler does exist for MATH LIBRARY_ERROR, 
then the status returned from the PMP$CAUSE_CONDITION procedure is used. 


The call-by-reference routine immediately returns to the calling program if it is 
returned to from MLP$ERROR_ PROCESSOR. . 


Refer to chapter 7, Vector Processing, for a discussion of vector error handling. 
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Scalar Classification Tables 6 


This chapter provides a series of tables that categorize the Math Library functions 
according to various classifications and provide information such as domains and ranges 
and types of results. 


Table 6-1 gives a summary of the math functions, grouping the functions by related 
generic and specific function names (alphabetized by generic name). COSD, SIND, and 
TAND are grouped with COS, SIN, and TAN, respectively. COSD, SIND, and TAND 
are not related to the generic functions because they return results in degrees. 


The functions in table 6-1 are grouped as follows: 


Absolute value (ABS, CABS, DABS, IABS) 
Inverse cosine (ACOS, DACOS) 

Imaginary part of a complex argument (AIMAG) 
Truncation (AINT, DINT) 

Natural logarithm (ALOG, CLOG, DLOG) 
Common logarithm (ALOG10, DLOG10) 
Remaindering (AMOD, DMOD, MOD) 
Nearest whole number (ANINT, DNINT) 
Inverse sine (ASIN, DASIN) 

Inverse tangent (ATAN, ATAN2, DATAN, DATAN2) 
Cosine (CCOS, COS, DCOS) 

Conjugate (CONJG) 

Cotangent (COTAN) 

Exponential (CEXP, DEXP, EXP) 
Hyperbolic cosine (COSH, DCOSH) 

Sine (CSIN, DSIN, SIN, SIND) _ 

Square root (CSQRT, DSQRT, SQRT) 
Inverse hyperbolic tangent (ATANH) 
Positive difference (DDIM, DIM, IDIM) 
Product (DPROD) 

Transfer of sign (DSIGN, ISIGN, SIGN) 
Hyperbolic sine (DSINH, SINH) 

Tangent (DTAN, TAN) 

Hyperbolic tangent (DTANH, TANH) 
Error function (ERF) 

Complementary error function (ERFC) 
Extract bits. (EXTB) 

Nearest integer (IDNINT, NINT) 

Insert bits (INSB) 

Random number generator (RANF) 
Returns random number seed (RANGET) 
Sets seed for random number generator (RANSET) 
Sum of 1 bits in one word (SUM1S) 


Table 6-2 shows the input domain! and output range for all of the math functions, 
except the exponentiation functions. For the exponentiation functions, table 6-3 lists the - 
bases, exponents, and results and table 6-4 summarizes the domains and ranges. 


1. Indefinite and infinite are not in the input domain unless specifically stated. This applies to tables 6-2 
and 6-4. 
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Summary of Math Functions 


Summary of Math Functions 


Table 6-1. 


Description 


Absolute value 


Inverse cosine 


Imaginary 
part of a 
complex 
argument 


Truncation 


Natural 
logarithm 


Common 
logarithm 
Remain- 


dering 


Nearest whole 
number 


Inverse sine 


6-2. Math Library 


Mathematical Functions 


Definition 
|x|; if x is complex, 
square root of 


((real x)*¥*2 + 
(imag x)**2) 


arccos(x) 


Imaginary part of 
(xr,xi) = xi 


int(x) 


log e (x) 


log 10 (x) 


x — int(x/y)*y 


int(x + 0.5), if x 
> 0 
int(x - 0.5), if x 
< 0 


arcsin(x) 


Function 
Name 


ABS 
CABS 
DABS 
IABS 


ACOS 
DACOS 


AIMAG 


AINT 
DINT 


ALOG 
CLOG 
DLOG 


ALOG10 
DLOG10 


AMOD 
DMOD 
MOD 


ANINT 


DNINT 


ASIN 
DASIN 


Type of 


Argument 


Real 
Complex 
Double 
Integer 


Real 
Double 


Complex 


Real 
Double 


Real 
Complex 
Double 


Real 
Double 


Real 
Double 
Integer 


Real 


Double 


Real 
Double 


Number of 
Arguments 


1 


Type of 
Result 


Real 
Real 
Double 
Integer 


Real 
Double 


Real 


Real 
Double 


Real 
Complex 
Double 


Real 
Double 


Real 
Double 
Integer 


Real 


Double 


Real 
Double 


(Continued) 
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Table 6-1. 


Description 


Inverse 
tangent 


Cosine 


Conjugate 


Cotangent 


Exponential 


Hyperbolic 
cosine 


Sine 


Square root 


Inverse 
hyperbolic 
tangent 
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Definition 


arctan(x) 


arctan(y/x) 


cos(x), where x is 
in radians 


cos(x), where x is 
in degrees 


Negation of 
imaginary part 


(xr,-xi) 


cotan(x), where x 
is in radians 


eFtx 


cosh(x) 
sin(x), where x is 
in radians 


sin(x), where x is 
in degrees 


x**(1/2) 


arctanh(x) 


Mathematical Functions (Continued) 


Function 
Name 


ATAN 
DATAN 
ATAN2 
DATAN2 


CCOS 
COS 

DCOS 
COSD 


CONJG 


COTAN 


CEXP 
DEXP 
EXP 


COSH 
DCOSH 


-CSIN 


DSIN 
SIN 
SIND 


CSQRT 
DSQRT 
SQRT 


ATANH 


Type of 
Argument 


Real 
Double 
Real 
Double 


Complex 
Real 
Double 
Real 


Complex 


Real 


Complex 
Double 
Real 


Real 
Double 


Complex 
Double 
Real 
Real 


Complex 
Double 
Real 


Real 


Summary of Math Functions 


Number of 
Arguments 


1 


2 


Type of 
Result 


Real 
Double 
Real 
Double 


Complex 
Real 
Double 
Real 


Complex 


' Real 


Complex 
Double 
Real 


Real 
Double 


Complex 
Double 
Real 
Real 


Complex 
Double 
Real 


Real 


(Continued) 
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Summary of Math Functions 


Table 6-1. Mathematical Functions (Continued) 


Description 


Positive 
difference 


Product 
Transfer of 
sign 
Hyperbolic 
sine 


Tangent 


Hyperbolic 
tangent 


Error function 


Complemen- 
tary error 
function 


Extract bits 


6-4 Math Library 


Definition 


x-y,ifx >y 


0,ifx =y 
x*y 
x|, ify = 0 


-|x|, if y < 0 


sinh(x) 


tan(x), where x is 


in radians 


tan(x), where x is 


in degrees 


tanh(x) 


erf(x) 


1 - erf(x) 


extb(x, il, i2); 


extracts bits from 


x starting with 


position il with 


length of i2 


Function 


Name 


DDIM 
DIM 
IDIM 


DPROD 


DSIGN 
ISIGN 
SIGN 


DSINH 
SINH 


DTAN 
TAN 
TAND 


DTANH 
TANH 
ERF 


ERFC 


EXTB 


Type of 
Argument 


Double 
Real 
Integer 


Real 


Double 
Integer 
Real 


Double 
Real 


Double 
Real 
Real 


Double 
Real 


Real 
Real 


X: 
Boolean 
Complex 
Double 
Integer 
Logical 
Real 

il: Integer 
i2: Integer 


Number of 
Arguments 


2 


Type of 
Result 


Double 
Real 
Integer 


Double 


Double 
Integer 
Real 


Double 
Real 


Double 
Real 
Real 


Double 
Real 


Real 
Real 


Boolean 


(Continued) 
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POON 


Summary of Math Functions 


Table 6-1. Mathematical Functions (Continued) 


Function Type of Number of 


Description Definition Name Argument Arguments 
Nearest int(x + 0.5), if x IDNINT Double 1 
integer = (Q 
int(x - 0.5), if x NINT Real 
< 0 
Insert bits insb(x, il, i2, y); INSB X,Y: 4 
inserts bits from x Boolean 
starting with Complex 
position il with Double 
length of i2 into Integer 
copy of y Logical 
Real 
il: Integer 
i2: Integer 
Random Random number in RANF None 0 
number range (0,1) 
generator 
Returns - Seed is in range RANGET Real 1 
random (0,1) 
number seed 
Sets seed for ranset(x) RANSET Real 1 
random 
number 
generator 
Sum of 1 bits sum1s(x) SUMI1S Boolean 1 
in one word - Complex 
Double 
Integer 
Real 


Type of 
Result 


Integer 


Integer 


Boolean 


Real 


Real 


Real 


Integer 
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Input Domains and Output Ranges 


Input Domains and Output Ranges 


Table 6-2. Input Domains and Output Ranges 


Function 


ACOS(x) 
DACOS(x) 


ALOG(x) 
CLOG(xr,xi) 


DLOG(x) 


ALOG10(x) 
DLOG10(x) 


ASIN(x) 
DASIN(x) 


ATAN(x) 
DATAN(x) 


ATAN2(x,y) 


DATAN2(x,y) 


ATANH(x) 


COS(x) 
CCOS(xr,xi) 


DCOS(x) 
COSD(x) 


COSH(x) 
DCOSH(x) 
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Input Domain 


1 
1 


x| 
[x| 


IN IN 


x > 0 

(xr, xi) # (0,0) 
(xr**2 + xi**2)**1/2 
in machine range 


x > 0 

x > 0 

x > 0 

Ix] = 1 

Ix] = 1 
-infinity = x = infinity 
-infinity = x = infinity 
y <0,x <0 
y <0,x = 0 
y=0,x < 0 

y =0,x > 0 
y>0,x < 0 
y >0,x = 0 

y <0,x < 0 

y <0,x = 0 

y =0,x < 0 

y =0,x > 0 

y >0,x < 0 

y >0,x = 0 
lx] < 1 

|x| < 2**47 
|xr| < 2**47 
|xi| < 4095*log(2) 
|x| < 2**47 

|x| < 2**47 


Ix] < 4095*log(2) 
|x] < 4095*log(2) 


Output Range 


0 ACOS(x) = pi 
0 = DACOS(x) = pi 


IN IN 


|ALOG(x)| < 4095*log(2) 
-pi < CLOG(xi) = pi 


|DLOG (x)| < 4095*log(2) 


|ALOG10(x)| < 4095*log(2) base 10 
IDLOG10(x)| < 4095*log(2) base 10 


-pi/2 = ASIN(x) = pi/2 
-pi/2 = DASIN(x) = pi/2 
-pi/2 = ATAN(x) = pi/2 
-pV/2 = DATAN(x) = pi/2 


-pi < ATAN2(x,y) < — pi/2 
pV/2 = ATAN2(x,y) = pi 
ATAN2(x,y) = —pi/2 
ATAN2(x,y) = pi/2 

-pi/2 < ATAN2(x,y) < 0 

0 = ATAN2(x,y) < pi/2 
-pi < DATAN2(x,y) < — pi/2 
pi/2 = DATAN2(x,y) = pi 
DATAN2(x,y) = —-pi/2 
DATAN2(x,y) = pi/2 

-pi/2 < DATAN2(x,y) < 0 
0 = DATAN2(x,y) < pi/2 


The set of valid real quantities. 


=] 
-1 


COS(x) = 1 
CCOS(x) 


IN IN 
IN 


1 


=1 


IN 
IN 


DCOS(x) 
COSD(x) 


1 


IN 
IN 


= 1 


COSH(x) = 1 
DCOSH(x) = 1 


(Continued) 
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Function 


COTAN(x) 
ERF(x) 
ERFC(x) 
EXP(x) 


CEXP(xr,xi) 


DEXP(x) 


SIN(x) 
CSIN(xr,xi) 


DSIN(x) 
SIND(x) 


SINH(x) 
DSINH(x) 


SQRT(x) 


CSQRT(xr,xi) 


DSQRT(x) 


TAN(x) 
DTAN(x) 


TAND(x) 


TANH(x) 
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Input Domain 


0 < |x| < 2**47 


IN 


-infinity = x 


IN 


-infinity = x 


x < 4095*log(2) and 
x = —4097*log(2) 

xr < 4095*log(2) and 
xr > —4097*log(2) 

xl < 2**47 

xi = -4097*log(2) 

x < 4095*log(2) & 


x = -4097*log(2) 


Ix] < 2**47 
[xr] < 2**47 
Ixi| < 4095*log(2) 
x] < 2**47 


|x] < 2**47 


Ix] < 4095*log(2) 
Ix] < 4095*log(2) 


x = 0 
(xr**2 + xi*¥*2)**1/2 + 
[xr| in machine range 


x = 0 


Ix] < 2**47 
Ix] < 2**47 


|x] < 2**47 
x cannot be exact odd 
multiple of 90 


-infinity = x = infinity 


infinity 


infinity 
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Input Domains and Output Ranges (Continued) 


Output Range 


The set of valid real quantities. 


0 = ERF() = 1 
0 = ERFC(x) = 2 
0 < EXP(x) 


The set of valid complex quantities. 


The set of valid double precision 
quantities. 


I 
—_ 
IN 


SIN(x) = 1 


-1 = DSIN(x) = 1 


I 
—_ 
IN 


SIND(x) 


IN 
—_ 


SQRT(x) = 0 
Value in right half of plane 
CSQRT(xr) = 0) 


The set of valid double precision 
quantities. 


The set of valid real quantities. 
The set of valid double precision 
quantities. 


The set of valid real quantities. 


-1 = TANH(xs) = 1 
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Exponentiation Functions 


Exponentiation Functions 


Table 6-3 illustrates that the result type of an exponentiation function is determined by 
the order of precedence of the two input arguments. The result of exponentiation 
always takes the type of the argument with the higher precedence according to the 
following hierarchy: 


1. Integer (the lowest precedence) 
2. Single precision floating-point 

3. Double precision floating-point 

4. Complex (the highest precedence) 


Table 6-3 lists the bases, exponents, and result types of the exponentiation functions by 
order of precedence. Table 6-4 summarizes the input domains and output ranges of the - 
exponentiation functions. 
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Exponentiation Functions 


Table 6-3. Arguments and Results of the Exponentiation Functions 


Name 


ITOI 
ITOX 


ITOD 


ITOZ 
XTOI 


XTOX 
XTOD 
XTOZ 
~ DTOI 
DTOX 
DTOD 
DTOZ 


ZTOI 
ZTOX 


~ ZTOD 


ZTOZ 


Base 


Integer 


Integer 


Integer 


Integer 


Single 
precision 
floating-point 


Single 
precision 
floating-point 


Single 
precision 
floating-point 


Single 
precision 
floating-point 


Double 
precision 
floating-point 


Double 
precision 
floating-point 


Double 
precision 
floating-point 


Double 
precision 
floating-point 
Complex 


Complex 


Complex . 


Complex 


Exponent 


Integer 


Single precision 
floating-point 


Double precision 
floating-point 


Complex 


Integer 


Single precision 
floating-point 


Double precision 
floating-point 


Complex 


Integer 


Single precision 
floating-point 


Double precision 
floating-point 


Complex 


Integer 


Single precision 
floating-point 


Double precision 
floating-point 


Complex 


Result Type! 


Integer 


Single precision floating-point 
Double precision floating-point 


Complex 


Single precision floating-point 


Single precision floating-point 


Double precision floating-point 


Complex 


Double precision floating-point 


Double precision floating-point 


Double precision floating-point 


Complex 


Complex 


Complex 


Complex 


Complex 


1. The argument (base or exponent) with the higher precedence always determines the 
number type of the result. 
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Exponentiation Functions 


Table 6-4. Domains and Ranges of the Exponentiation Functions 


Type of 
Name Argument Input Domain Output Range 
ITOI Integer |x*#y| < 2**63; if x = 0, then y > 0 The set of valid 
Integer integer 
quantities 
ITOX Integer x = 0; if x = 0, then y > 0 x**y = 0 
Real 
ITOD Integer x = 0; if x = 0, then y > 0 x**¥y => 0 
Double 
ITOZ Integer x = 0; if x = 0, then yr > 0, yi = 0 x**¥y => 0 
Complex 
XTOI Real if x = 0, then y > 0 The set of valid 
Integer . real quantities 
XTOX Real x = 0; if x = 0, then y > 0  xtty = Q 
Real 
XTOD Real x = 0; if x = 0, then y > 0 . x**y => 0 
Double 
XTOZ Real ifx = 0, then yr > 0, yi = 0 The set of valid 
Complex complex 
quantities 
DTOI Double | if x = 0, then y > 0 The set of valid 
Integer _ double precision 
> quantities 
DTOX Double x = 0; if x = 0, then y > 0 x*¥*y = 0 
Real 
DTOD Double x = 0; if x = 0, then y > 0 x*¥*y = 0 
Double . | . | 
DTOZ Double if x = 0, then yr > 0, yi = 0 | The set of valid 
Complex double precision 
quantities 
(Continued) 
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Exponentiation Functions 


Table 6-4. Domains and Ranges of the Exponentiation Functions (Continued) 


Type of 
Name Argument Input Domain Output Range 
ZTOI Complex if (xr,xi) = (0,0), then y > 0 The set of valid 
Integer complex 
quantities 
ZTOX Complex if (xr,xi) = (0,0) then y > 0 The set of valid 
Real complex 
quantities 
ZTOD Complex if (xr,xi) = (0,0) then y > 0 The set of valid 
Double complex 
quantities 
ZTOZ Complex if (xr,xi) = (0,0) then y > 0, yi = 0 The set of valid 
Complex complex 


quantities 
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Vector Processing 7 


This chapter discusses the vector processing capabilities of the Math Library, including 
both single argument and double argument vector math functions. This chapter also 
discusses vector error handling. 


Vector Functions 


Vector math functions accept vectors as arguments and return vectors as results. A 
vector is a one-dimensional set of numbers. 


While the vector math functions are available and can be referenced on any CYBER 
180 mainframe model, they perform array-processing only on models which include 
vector hardware facilities, currently limited to the CYBER 990/995 Series running 
FORTRAN Version 2. 


If a vector math function is called on a non-vector machine, an unimplemented 
instruction trap (hardware condition) may occur (the vectorization is not implemented). 


The FORTRAN Version 2 compiler guarantees that the length (L) of the vector sent to 
the Math Library will be within the range 0 = L = 512 words. When the vector 
length is not within this valid range, an error message is displayed. See the section in 
this chapter entitled Vector Error Handling. When the length of the vector argument 
sent to the Math Library vector routine is zero, no operation occurs and the contents of 
the vector are returned without any values changed. 


Vector Function Calling Routines 


Scalar functions (depending upon the calling language) can be called by a 
call-by-reference or a call-by-value calling routine (linkage). Vector routines always use 
the call-by-reference linkage. 


Under call-by-reference, register A4 points to the actual parameter list. Vector routines 
can have four different parameter lists as described in tables 7-1 through 7-4. 


The calling sequence for all vector functions has one entry point defined for each 
function. In all cases, register A4 contains the Process Virtual Address (PVA) to the 
first entry in the parameter list. 


The Math Library provides two types of vector processing functions: 
® Single Argument Vector Math Functions 
@ Double Argument Vector Math Functions 


The following sections discuss these types of functions. 
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Vector Functions 


Single Argument Vector Math Functions 


The Math Library provides the following single argument vector processing functions: 


ACOS CSIN DTAN 
ALOG CSQRT DTANH 
ALOG10 DACOS ERF 
ASIN DASIN ERFC 
ATAN DATAN EXP 
ATANH DCOS SIN 
CCOs DCOSH SIND 
CEXP DEXP SINH 
CLOG DLOG SQRT 
Cos DLOGI0 TAN 
COSD DSIN TAND 
COSH DSINH TANH 
COTAN DSQRT . 


Table 7-1 describes the internal representation of the parameter list for real, double 
precision, and complex single argument vector math functions. Single valued vector 
routines always follow this format. Each word is a decimal value. 


Table 7-1. Parameter List for Single Argument Vector Math Functions 


Word Description of Contents 

Word 1 Pointer to the result array. 

Word 2 Pointer to the source array. 

Word 3 Pointer to the result array descriptor. 
Word 4 Pointer to the source array descriptor. 
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Vector Functions 


Double Argument Vector Math Functions 


The Math Library provides the following double argument vector processing functions: 


ATAN2 DTOZ XTOZ 
DATAN2 ITOZ ZTOD 
DTOD XTOD ZTOI 

DTOI XTOI ZTOX 
DTOX XTOX ZTOZ 


The double argument vector math functions are divided into three categories: 

function_name(scalar, vector) See table 7-2 for a (scalar, vector) parameter list. 
function_name(vector, scalar) See table 7-3 for a (vector, scalar) parameter list. 
function_name(vector, vector) See table 7-4 for a (vector, vector) parameter list. 


where function_name is a double argument function name, such as ATAN2. 


Double Argument Vector Math Functions (Scalar, Vector) 
Table 7-2 provides the internal representation of the parameter list for double 


argument vector math functions where argument 1 is scalar and argument 2 is vector. 
Each word is a decimal value. 


Table 7-2. Parameter List for (Scalar, Vector) Functions 


Word Description of Contents 

Word 1 Pointer to the result array. 

Word 2 Pointer to the source scalar (argument 1). 

Word 3 Pointer to the source array (argument 2). 

Word 4 Pointer to the result array descriptor. 

Word 5 0 

Word 6 Pointer to the source array descriptor (argument 2). 
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Vector Functions 


Double Argument Vector Math Functions (Vector, Scalar) 
Table 7-3 provides the internal representation of the parameter list for double 
argument vector math functions where argument 1 is vector and argument 2 is scalar. 


Each word is a decimal value. 


Table 7-3. Parameter List for (Vector, Scalar) Functions 


Word Description of Contents 

Word 1 Pointer to the result array. 

Word 2 Pointer to the source array (argument 1). 

Word 3 Pointer to the source scalar (argument 2). 

Word 4 Pointer to the result array descriptor. 

Word 5 Pointer to the source array descriptor (argument 1). 
Word 6 0 


Double Argument Vector Math Functions (Vector, Vector) 
Table 7-4 provides the internal representation of the parameter list for double 


argument vector math functions where argument 1 is vector and argument 2 is vector. 
Each word is a decimal value. 


Table 7-4. Parameter List for (Vector, Vector) Functions 


Word Description of Contents 

Word 1 Pointer to the result array. 

Word 2 Pointer to the source array (argument 1). 

Word 3 Pointer to the source array (argument 2). 

Word 4 Pointer to the result array descriptor. 

Word 5 Pointer to the source array descriptor (argument 1). 
Word 6 Pointer to the source array descriptor (argument 2). 
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Vector Functions 


Result Array and Source Array Descriptors 


Table 7-5 provides the internal representation of the result array descriptor and the 
source array descriptor for all vector math functions. 


Table 7-5. Result Array and Source Array Data Locations 


Word Description of Contents 
Word 1 Number of elements in vector. 
Word 2 _. Distance (or stride) measured in terms of array elements between two 


consecutive elements of the same dimension. Always equal to one for 
the Math Library. 


Word 3 - Lower bound of array. Always zero for the Math Library. 


60486513 H Vector Processing 7-5 


Vector Error Handling 


Vector Error Handling 


The vector math functions use call-by-reference error handling. For example, if an 
argument within a set of arguments is illegal or produces an out-of-range value, an 
error message is displayed for that argument. The first argument in error is supplied 
in the error message. The default error value (usually an indefinite value indicated by 
+IND) is placed in the result location corresponding to the argument in error within 
the set. 


Processing continues and correct results are generated for all arguments which are not 
in error. However, once an argument is found to be in error, further arguments which 
are in error are not detected and results are not guaranteed. 


NOTE 


For all vector routines, only the first illegal or out-of-range-producing argument 
produces an error message. 
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Function Descriptions 8 


This chapter provides a summary of each Math Library function. The functions are 
organized alphabetically. Each function description includes the following: 


e A description including the entry points for the function and the input domains and 
output ranges for the arguments in each function 


@ The call-by-reference routine 

@ The call-by-value routine 

e An example call from Ada, C, FORTRAN, or Pascal 

The following additional information is included, if applicable: 

@ Conditions that cause an argument to be invalid, resulting in an error 
@ The vector routine 

® Formulas used to compute the result 

@ Error analysis and the effect of argument error 


Entry points to the call-by-reference and call-by-value routines are places in the © 
routines where execution can begin. Some routines can evaluate more than one function 
(for example, one algorithm may calculate a generic function and a specific function). 
Some routines call auxiliary routines (as described in chapter 9, Auxiliary Routines) to 
compute a portion of the function. : 


NOTE 


If a category of information is not applicable (for example, Vector Routine, Error 
Analysis, or Effect of Argument Error), it is omitted from the function description. 
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Generic and Specific Names 


Some functions have a generic name and one or more specific names. For example, 
ABS is a generic name; CABS, DABS, and JABS are specific names. For these 
functions, either the generic name or one of the specific names can be used. The 
generic name provides more flexibility because it can be used with any of the valid 
data types; except for functions performing type conversion, nearest integer, and 
absolute value with a complex argument, the type of the argument determines the type 
of the result. 


A 2-byte or 4-byte integer or byte value, used as an argument to a function, is 

converted to a full word (8-byte) integer before being used as an argument. The 

conversion does not change the sign of the argument. A function accepting integer, 

real, complex or double precision type arguments also accepts boolean arguments. A 

boolean argument is converted to integer if it is an allowable argument type; 

otherwise, it is converted to real before computation. However, only a specific name 

can be used as an actual argument when passing the function name to a user-defined 

subprogram. Using a specific name requires a specific argument type. 


For example, the generic function LOG computes the natural logarithm of an 
argument. Its argument can be real, double precision, complex or boolean (converted to 
real). The type of the result is the same as the type of the argument. Specific functions 
ALOG, DLOG, and CLOG also compute the natural logarithm. The specific function 
ALOG computes the log of a real or boolean argument and returns the result. The 
specific function DLOG is for double precision (or boolean) arguments and double 
precision results and the specific function CLOG is for complex (or boolean) arguments 
and complex results. 
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ABS 


ABS computes the absolute value of an argument. It accepts a real argument and 
returns a real result. 


The call-by-reference entry points are MLP$RABS and ABS, and the call-by-value entry 
point is MLP$VABS. 


The input domain is the collection of all valid real quantities. The output range is 
included in the set of nonnegative real quantities. 


Call-By-Reference Routine 


No errors are generated by ABS. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The argument is returned with its sign bit forced positive. The rightmost 63 bits 
remain the same. . 


Example of ABS Called From FORTRAN . 


Source Code: 


PROGRAM ABS_EXAMPLE 


EXTERNAL ABS 

REAL r,t 

r=-88.9 

t=ABS(r) 

PRINT *, “Absolute value = ’, t 
END 


Output: 


Absolute value = 88.9 
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ACOS 


ACOS computes the inverse cosine function. It accepts a real argument and returns a 
real result. 


The call-by-reference entry points are MLP$RACOS and ACOS, the call-by-value entry 
point is MLP$VACOS, and the vector entry point is MLP$ACOSV. 


The input domain is the collection of all valid real quantities in the interval [-1.0,1.0]. 
The output range is included in the set of nonnegative real quantities less than or 
equal to pi. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than 1.0. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


Formulas used in the computation are: 


arcsin(x) = -arcsin(-x), x < -.5 

arcos(x) = pi - arcos(-x), x < -.5 

arcsin(x) = x + x**3*s*((w + 2 -j)*w + a+ m/(e - x**2)), 
where ~.5 < x < .5 

arcos(x) = pi/2 - arcsin(x), -.5 <= x < .5 

arcsin(x) = pi/2 - arcos(x), .5 <= x < 1.0 


arcos(x) = arcos(1-ITER((1 - x),n))/2**n, .5 <= x < 1.0 
arcsin(1) = pi/2 


arcos(1) = 0 
where: 
w = (x**2 - c)*z +k 
z = (x**2 + r)x**2 + j 


ITER(y,n) = n iterations of y = 4%y - 2*y**2 
The constants used are: 


= 3.173 170 078 537 13 
= 1.160 394 629 739 02 
= 50.319 055 960 798 3 
-2.369 588 855 612 88 
.226 467 970 799 17 
= -35.629 481 597 455 5 
= 37.459 230 925 758 2 
= 349.319 357 025 144 
= .746 926 199 335 419*10**-3 


nm rem OF 30 7 
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ACOS 


The approximation of arcsin(—.5,.5) is an economized approximation obtained by varying 
r,é,m,...,S. 


The algorithm used is: 


a. If ACOS entry, go to step g. 
b. If |x| > = .5, go to steph. 


= 0 (Loop counter). 

= X 

x**2 

= 0, if ASIN entry. 

= pi/2, if ACOS entry. 


ccoxtino 3 
HT] 


= (y Purysy et 

=(y -c )*z + k 

q + -stqty*((w + 2 - j)*w+a+m/(e - y)) 
=u-op 

1 = p/2**n 


<UDUUGU SEN 


e. If ASIN entry, go to step k. 


f. If x is in (-.5,1.0), return. 
XF = 2*u - (Y1) 
Return. 


g. If |IxI < .5, go to step c. 


h. If x = 1.0 or -1.0, go to step 1. 
If x is invalid, go to step m. 
n = 0 (Loop counter). 
y = 1.0 - {xl, and normalize y. 


i. h 4ty - 2*y**2 
n=n + 1.0 
If 2*y <2 = sart(3) = .267949192431, y = h, and go to step i. 


j. q#= 1.0 - h, and normalize q. 
y = q**2 
u = pi/2 
Go to step d. 


k. Y1 =u - (Y1), and normalize Y1. 
Affix sign of x to Y1 = XF. 
Return. 


1. XF = pi/2, if x = 1.0. 
XF = -pi/2, if x = -1.0. 
If ASIN entry, return. 
XF = 0, if x = 1.0. 
XF = pi, if x = -1.0. 
Return. 


m. Return. 
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Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than 1.0. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The maximum absolute value of relative error of the ACOS approximation over (-.5,.5) 
is 1.996*E-15. | 


The function ACOS was tested against the Taylor series. Groups of 2,000 arguments 
were chosen randomly from given intervals. Statistics on relative error were observed. . 
Table 8-1 shows a summary of these statistics. 


Table 8-1. Relative Error of ACOS 


Root Mean 
Interval From Interval To Maximum Square 
-.1250E + 00 .1250E+00 .4916E-14 .3233E-14 
-.1000E+ 01 -.7500E+00 .5875E-14 .2068E-14 
.7500E + 00 .1000E+01 .1987E-13 .TT4A9E-14 
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Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/(1.0 — x**2)**.5. 


Example of ACOS Called From FORTRAN 


Source Code: 


PROGRAM ACOS_EXAMPLE 


C 
x=0.5 
PRINT *, “Inverse cosine of x is:’ 
PRINT *, ACOS(x) 
END 
Output: 


Inverse cosine of x is: 
1.047197551197 


60486513 H Function Descriptions 8-7 


AIMAG 


AIMAG 


AIMAG returns the imaginary part of an argument. It accepts a complex ereument and 
returns a real result. 


The call-by-reference entry points are MLP$RAIMAG and AIMAG, and the call-by-value 
entry point is MLP$VAIMAG. 


The input domain is the collection of all valid complex quantities. The output range is 
included in the set of valid real quantities. 


Call-By-Reference Routine 


No errors are generated by AIMAG. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The imaginary part of the complex argument is returned. The real part of the 
argument is not used. 


Example of AIMAG Called From FORTRAN 


Source Code: 


PROGRAM AIMAG_EXAMPLE 


C 

EXTERNAL AIMAG 
COMPLEX xray 
xray=(3.14159, -1.0) 
PRINT *, “The imaginary part of xray is:’ 
PRINT *, AIMAG (xray) 
END 

Output: 


The imaginary part of xray is: 
-1. 


NOTE 


AIMAG accepts a complex argument and returns a real result. 
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AINT 


AINT returns an integer part of an argument after truncation. It accepts a real 
argument and returns a real result. 


The call-by-reference entry points are MLP$RAINT and AINT, and the call-by-value 
entry point is MLP$VAINT. 


The input domain is the collection of all valid real quantities. The output range is 
included in the set of valid integer quantities. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


The argument is added to a special floating-point zero that forces truncation. The 
result is returned. 


Example of AINT Called From FORTRAN 


Source Code: 


PROGRAM AINT_EXAMPLE 


C 
EXTERNAL AINT 
x= 1234 .567890 
PRINT *, “The integer part of x is:’ 
PRINT *, AINT(X) 
END 
Output: 


The integer part of x is: 
1234. 
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ALOG 


ALOG computes the natural logarithm function. It accepts a real argument and returns 
a real result. 


The call-by-reference entry points are MLP$RALOG and ALOG, the call-by-value entry 
point is MLP$VALOG, and the vector entry point is MLP$ALOGV. 


The input domain is the collection of all valid, positive real quantities. The output 
range is included in the set of valid real quantities whose absolute value is less than 
4095*log(2). 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

It is equal to zero. 

It is less than zero. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


If x is valid, let y be a real number in [1, 2) aa n an integer such that x = a ai 
Log(x) is evaluated by: ; 


log(x) = log(y) + n*log(2) 


To evaluate log(y), the interval [1, 2) is divided into 33 subintervals such that on each 
the abs(t) < 1/129 where t = (y - c)/(y + c). To achieve this, the subintervals are 
offset by 1/64. The subintervals are: 


[1, 65/64) 
[65/64, 67/64) 


[125/64, 127,64) 
[127/64, 2) 


Log(y) is then computed using the identity: 
log(y) = log(c) + log((1 + t)/(1 - t)) 


and the center point c is chosen close to the midpoint of the subinterval containing y, 
except for the first and last subintervals, where the center points are 1 and 2, 
respectively. By selecting these center points, it ensures that abs(t) < 1/129. 
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ALOG 


Log ((1 + t)/(1 - t)) is approximated with a 7th degree minimax polynomial of the 
form: 


2°t. + COtt**3: + chet e*5-? C77 te *7 


The coefficients are: 


c3 = .6666666666667 
c5 = .3999999995486 
C7 = .28573431769 17 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is equal to zero. 
It is less than zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-2 shows a summary of these statistics. 


Table 8-2. Relative Error of ALOG 


Root Mean 
Test Interval From Interval To Maximum Square 
ALOG(x) against .7071E +00 9375E+00 .1782E-13 .54638E-14 
ALOG(17x/16)— 
ALOG(17/16) 
ALOG(x*x) against .1600E + 02 .2400E+03 .7082E-14 .2035E-14 
2*LOG(x) 
ALOG(x) against Taylor 1-.1526E-04 1+.1526E-04 .1417E-13 .5197E-14 
series expansion of 
ALOG(1 + y) 
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ALOG 


Total Error 


The final calculation of log(x) is done by adding the following terms in the order below 
to achieve maximum precision: 


log(x) = n*(log(2) - factor) + 
. (((c7#t2 + c5)*t2 + c3)*t2)*t + 
t + 
t + 
(log(c)/2) + (factor/2)*n + 
(log(c)/2) + (factor/2)*n 


The values of c and log(c)/2 for each subinterval are stored in a table. Factor is the 
nearest floating-point value with 8 bits of precision to log(2). Thus, the single precision 
representation of log(2) - factor is accurate to 56 bits of precision. The sum log(c) + 
factor*n is split into two equal parts to provide extra precision during the accumulation 
of the sum of terms. 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/x. 
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Example of ALOG Called From FORTRAN 


Source Code: 


PROGRAM ALOG_EXAMPLE 


C 
x=100.0 
PRINT *, “The natural logarithm of x is:’ 
PRINT *, ALOG(x) 
END 
Output: 


The natural logarithm of x is: 
4.605170 185988 
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ALOG10 


ALOG10 computes the common logarithm function. It accepts a real argument and 
returns a real result. 


The call-by-reference entry points are MLP$RALOGI0 and ALOGIO, the call-by-value 
entry point is MLP$VALOGIO, and the vector entry point is MLP$ALOGI0V. 


The input domain is the collection of all valid, positive real quantities. The output 
range is included in the set of valid real quantities whose absolute value is less than 
4095*log(2) base 10. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

It is equal to zero. 

It is less than zero. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 
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Call-By-Value Routine 


If x is valid, let y be a real number in [1, 2) and n an integer such that x = y*2**n. 
Log10(x) is evaluated by: 


10g10(x) = 10910(y) + n*1log10(2) 


To evaluate logl10(y), the interval [1, 2) is divided into 33 subintervals such that on 
each the abs(t) < 1/129 where t = (y — c)/(y + c). To achieve this, the subintervals 
are offset by 1/64. The subintervals are: 


[1, 65/64) 
[65/64, 67/64) 


[125/64, 127,64) 
[127/64, 2) 


Logl10(y) is then computed using the identity: 
log10(y) = 1log10(c) + 1ogi0((1 + t)/(1 - t)) 


and the center point c is chosen close to the midpoint of the subinterval containing y, 
except for the first and last subintervals, where the center points are 1 and 2, 
respectively. By selecting these center points, it ensures that abs(t) < 1/129. 


Log10((1 + t)/(1 — t)) is approximated with a 7th degree minimax polynomial of the 
form: 


C1*t + c3*t**3 + c5 + t**5 + C7**t**7 
The coefficients are: 


C1 = .8685889638065 
c3 = .2895296546022 
c5 . 1737177925653 
c7 . 1240928374639 
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Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is equal to zero. 
It is less than zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The function ALOG10 was tested against ALOG10(11x/10) - ALOG10(11/10). Groups of 
2,000 arguments were chosen randomly from the interval [.3162E+00,.9000E +00). 
Statistics on relative error were observed: maximum relative error was .3011E-13, root 
mean square relative error was .8125E-14. 


Total Error 


The final calculation of log10(x) is done by adding the following terms in the order 
below to achieve maximum precision: 


1og10(x) = n*(10g10(2) - factor) + 
(((c7*t2 + c5)*t2 + c8)*t2 + (cl - 1))*t + 
t + 
(log10(c) + factor*n) 


The values of c and logi0(c) for each subinterval are stored in a table. Factor is the 
nearest floating-point value with 8 bits of precision to log10(2). Thus, the single 
precision representation of log10(2) - factor is accurate to 56 bits of precision. The 
leading coefficient of the approximation is split into 1 and (cl - 1) to provide extra 
precision to the minimax polynomial approximation. 
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Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/x. 


Example of ALOG10 Called From FORTRAN 


Source Code: 


PROGRAM ALOG10_EXAMPLE 


C 
x=100.0 
PRINT *, “The common logarithm of x is:’ 
PRINT *, ALOG10(x) 
END 
Output: 


The common logarithm of x is: 
2. 
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AMOD 


AMOD returns the remainder of the ratio of two arguments. It accepts two real 
arguments and returns a real result. 


The call-by-reference entry points are MLP$RAMOD and AMOD, and the call-by-value 
entry point is MLP$VAMOD. 


The input domain is the collection of all valid real pairs (x,y) such that x/y is a valid 
real quantity, and y is not equal to 0. The output range is included in the set of valid 
real quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
y is equal to zero. 
x/y is infinite. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is branched to, and the result of the computation is 
returned to the calling program. 


Call-By-Value Routine 
Given the argument pair (x,y), the formula used for the AMOD computation is: 
x - aint (x/y)*y 


The quotient x/y is added to a special floating-point zero that forces truncation, to get 
n = aint(x/y); then the product of n and y is formed in double precision and subtracted 
from x in double precision. The most significant word of the result is returned. If the 
result is nonzero, it has the sign of x. 
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Example of AMOD Called From FORTRAN 


Source Code: 


PROGRAM AMOD_EXAMPLE 


EXTERNAL AMOD 

x=750.0 

y=140.0 

PRINT *, “The AMOD of x and y is:’ 
PRINT *, AMOD(x,y) 

END 


Output: 


The AMOD of x and y is: 
50. 


Example of AMOD Called From Pascal 


Source Code: 


program AMOD_EXAMPLE (output); 
var x, Y, 2 : REAL; 


begin 

x := 750.0; 

y := 140.0; 

z := AMOD (x, y); 

writeln ( ’ The AMOD of x and y is ’, z :1:1); 
end. 


Output: 


The AMOD of x and y is 50.0 
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ANINT 


ANINT returns the nearest whole number to an argument. It accepts a real argument 
and returns a real result. 


The call-by-reference entry points are MLP$RANINT and ANINT, and the call-by-value 
entry point is MLP$VANINT. 


The input domain is the collection of all valid real quantities. The output range is 
included in the set of valid integer quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 
If the argument is = 0, .5 is added to it, and the result is added to a special 


floating-point zero that forces truncation. If the argument is < 0, -.5 is added to it, 
and the result is added to a special floating-point zero that forces truncation. 
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Example of ANINT Called From FORTRAN 


Source Code: 


PROGRAM ANINT_EXAMPLE 


C 
EXTERNAL ANINT 
X=1234. 1234 
y=12.12 
PRINT *, “The nearest whole number to x is:’ 
PRINT *, ANINT(x) 
PRINT *, “The nearest whole number to y is:’ 
PRINT *, ANINT(y) 
END 

Output: 

The nearest whole number to x is: 

1234. 

The nearest whole number to y is: 

12. 
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ASIN 


ASIN computes the inverse sine function. It accepts a real argument and returns a real 
result. 


The call-by-reference entry points are MLP$RASIN and ASIN, the call-by-value entry 
point is MLP$VASIN, and the vector entry point is MLP$ASINV. 


The input domain is the collection of all valid real quantities in the interval [-1.0,1.0]. 
The output range is included in the set of valid real quantities in the interval 
[-pi/2,pi/2]. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than 1.0. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


Formulas used in the computation are: 


arcsin(x) -arcsin(-x), x < -.5 

arcos(x) = pi - arcos(-x), x < -.5 

arcsin(x) = x + x**3*s*((w + z -j)*w + a+ m/(e - x**2)), 
where -.5 < x < .5 

arcos(x) = pi/2 - arcsin(x), -.5 <= x < .5 

arcsin(x) = pi/2 - arcos(x), .5 <= x < 1.0 

arcos(x) = arcos(1-ITER((1 - x),n))/2**n, .5 <= x < 1.0 

arcsin(1) = pi/2 

arcos(1) = 0 


where: 


w= (x**2 - c)*z +k 
z (x**2 + r)x**2 + j 
ITER(y,n) = n iterations of y = 4*y - 2*y**2 


The constants used are: 


= 3.173 170 078 537 13 

= 1.160 394 629 739 02 

= 50.319 055 960 798 3 

= -2.369 588 855 612 88 

.226 467 970 799 17 

= -35.629 481 597 455 5 

= 37.459 230 925 758 2 

= 349.319 357 025 144 

= -746 926 199 335 419*10**-3 


now ree 30 73 
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The approximation of arcsin(—.5,.5) is an economized approximation obtained by varying 
r,é,m,...,S. 


The algorithm used is: 


If ACOS entry, go to step g. 


If |x| > .5, go to step h. 


If ASIN entry, go to step k. 


If x is in (-.5,1.0), return. 


If [x] < .5, go to step c. 


a. 

b. 

c. ne 
qe 
y= 
uU = 
uU = 

d. Ze 
we 
p= 
p = 
Y1 

e. 

f. 

XF 
Ret 

g. 

h. If 
If 

i. he 
n= 

Jj. qs 
y= 
uU = 
Go 

k. YT 
Aff 
Ret 

1. XF 
XF 
If 
XF 
XF 
Ret 

m. Ret 
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0 (Loop counter). 

x 

x**2 

0, if ASIN entry. 
pi/2, if ACOS entry. 


(y t+ r)*ty + i 
(y - c )*z +k 


q + s*qty*((w + z - j)*wt+a+t+m/(e - y)) 


u- p 
= p/2**n 


= 2*y - (Y1) 
urn. 


xX = 1.0 or -1.0, go to step 1. 
xX is invalid, go to step m. 


n = 0 (Loop counter). 


y = 1.0 - |x], and normalize y. 
4ty - 2ty**2 
n+ 1.0 


1.0 - h, and normalize q. 


to step d. 


=u - (Y1), and normalize Y1. 
ix sign of x to Y1 = XF. 


urn. 


= pi/2, if x = 1.0. 

= -pi/2, if x = -1.0. 
ASIN entry, return. 

= 0, if x = 1.0. 

= pi, if x = -1.0. 
urn. 


urn. 


If 2*y < 2 - sqrt(3) = .267949192431, y = h, and go to step i. 
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Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than 1.0. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The maximum absolute value of relative error of the ASIN Bpproxmnenon over (—.5,.5) 
is 1.996*E-15. 


The function ASIN was tested against the Taylor series. Groups of 2,000 arguments 


were chosen randomly from given intervals. Statistics on relative error were observed. 
Table 8-3 shows a summary of these statistics. 


Table 8-3. Relative Error of ASIN 


Root Mean 
Interval From Interval To Maximum Square 
~.1250E +00 .1250E+00 .7101E-14 .2763E-14 
.7500E + 00 1000E+01 .8378E-14 .3462E-14 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/(1.0 — x**2)**.5. 
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Example of ASIN Called From FORTRAN 


Source Code: 


PROGRAM ASIN_EXAMPLE 

x=0.5 

PRINT *, “The inverse sine of x is:’ 
PRINT *, ASIN(X) 

END 


Output: 


The inverse sine of x is: 
- 5235987755983 
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ATAN 


ATAN computes the inverse tangent function. It accepts a real argument and returns a 
real result. 


The call-by-reference entry points are MLP$RATAN and ATAN, the call-by-value entry 
point is MLP$VATAN, and the vector entry point is MLP$ATANV. 


The input domain is the collection of all valid real quantities. The output range is 
included in the set of valid real quantities in the interval [-pi/2,pi/2]. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if it is indefinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


The argument x is transformed into an argument y in the interval [0,1/16] by the 
range reduction formulas: 


arctan(u) = -arctan(-u), if u <0 

arctan(u) pi/4 + (pi/4 - arctan(1/u)), if u > 1.0 

arctan(u) arctan(k/16) + arctan((u - k/16)/(1.0 + u*k/16)), 
if 0 <u < 1.0, and k is the greatest integer not 
exceeding 16*u. 


Finally, arctan(y) (for y in [0,1/16]) is computed by the polynomial approximation: 


arctan(y) =y + a(1)*y**3 +: a(2)*y**5 + a(3) *y**7 + a(4) *y**9 


where: 
a(1) = -.333 333 333 333 128 45 
a(2) = .199 999 995 801 446 4 
a(3) = -.142 854 130 508 745 0 
a(4) = .110 228 161 612 614 9 


The coefficients of this polynomial are those of the minimax polynomial approximation 
of degree 3 to the function f over (0,1/4), where f(u**2 = (arctan(u) - u)/u**3. 


Vector Routine 
The argument is checked upon entry. It is invalid if it is indefinite. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


1. Algorithm and Constants, Copyright 1970 by Krzysztof Frankowski, Computer Information and Control 
Science, University of Minnesota. 
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Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-4 shows a summary of these statistics. 


Table 8-4. Relative Error of ATAN 


Root Mean 
Test Interval From Interval To Maximum Square 
ATAN(x) against -.6250E-01 .6250E-01 .7102E-14 .3647E-14 
truncated Taylor series 
2*ATAN(x) against .2679E + 00 A142E+00 .1355E-13 4023E-14 
ATAN(2x/(1 - x*x)) .4142E +00 .1000E+01 .1763E-13 .5931E-14 
ATAN(x) against .6250E-01 .2679E+00 .7117E-14 .2605E-14 


ATAN(1/16) + ATAN((x 
- 1/16) + x/16)) 


Effect of Argument Error 


If a small error e occurs in the argument, the error in the result y is given 
approximately by e/(1+y**2). 


Example of ATAN Called From FORTRAN 


Source Code: 


PROGRAM ATAN_EXAMPLE 


C 
x=0.5 
PRINT *, “The inverse tangent of x is:’ 
PRINT *, ATAN(x) 
END 
Output: 


The inverse tangent of x is: 
-4636476090008 
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ATANH 


ATANH computes the inverse hyperbolic tangent function. It accepts a real argument 
and returns a real result. 


The call-by-reference entry points are MLP$RATANH and ATANH, the call-by-value 
entry point is MLP$VATANH, and the vector entry point is MLP$ATANHV. 


The input domain is the collection of all valid real quantities whose absolute value is 
less than 1.0. The output range is included in the set of valid real quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than or equal to 1.0. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


The argument range can be reduced to the interval [0,1.0] by the identity atanh(-x) = 
-atanh(x). The expression atanh(x) = .5*In((1.0 + x)/(1.0 - x)) is formed by using the 
definition tanh(x) = (e**x - e**-x)/(e**x + e**-x). 


The argument range of the log can be reduced to the interval [.75,1.5] by using the 
property In(a*b) = In(a) + In(b), and extracting the appropriate multiple of In(2): 


atanh(x) = .5*n*1In(2) + .5*1n(2**-(n)*(1.0 + x)/(1.0 - x)) 


The argument range is reduced to the interval [-.2,.2] by writing the argument of log 
in the form (1.0 + y)/(1.0 - y), and substituting atanh(y): 


atanh(x) = .5*n*1n(2) + atanh| 2**-n*(1.0 + x) - (1.0 - x) 
2**-n*(1.0 + x) + (1.0 - x) 


The value of n such that 2**-n*(1.0 + x)/(1.0 - x) is in the interval [.75,1.5] is the 
same as the value of n such that 2**-n*(1.0 + x)/(.75*(1.0 - x)) is in the interval 
[1.0,2.0]. If .75*(1.0 - x) is written as a*2**m, where a is in interval [1.0,2.0], then 
2**(—n -— m)*(1.0 + x)/a must be in interval [1.0,2.0]. If (1.0 + x) = a, then -n - m 
= 0 and n = -m. If (1.0 + x) < a, then -n - m = 1.0 and n = 1.0 - m. 


The function atanh(z) in the interval [-.2,.2] is approximated by z + z**3*p/q, where p 
and q are 4th order even polynomials. For atanh(z), the coefficients of p and q were 
derived from the (7th order odd)/(4th order even) minimax (relative error) rational form 
in the interval [-.2,.2]. 
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Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 1.0. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 
For abs(x) < .2, n equals zero, and the expected bound of the error is 4.8E-15. 


For abs(x) = .5, the term n*(In(2)/2) dominates. This term is computed as n*(In(2)/2 —- 
.125) - n*.125 — n*.125 because the rounding error in representing In(2)/2 is large; the 
above form makes the rounding error relatively small. Since n*.125 is exact and the 
dominating form, the two additions in (other)n*.125 + n*.125 dominate the error, and 
the expected relative error is 8.3E-15 in this region. 


For .2 = abs(x) < .5, n equals one, and the term z = (.5*(1.0 + x) - (1.0 - 
x))/(.5*(1.0 + x) + (1.0 - x)) may be relatively large. For abs(x) < 0.25, the 
subtraction 1.00 - x = .5 - x + .5 loses two bits of the original argument. Also, z is 
negative in this range, and some cancellation occurs in the final combination of terms, 
costing about one unit in the last place (ulp). The expected upper bound in the region 
2 < abs(x) < 0.25 is 19.4E-15. 


A group of 10,000 arguments was chosen randomly from the interval [-1.0,1.0]. The 
maximum relative error of these arguments was found to be .3304E-13. 


Effect of Argument Error 
For small errors in the argument x, the amplification of absolute error is 1.0/(1.0 - 


x**2), and that of relative error is x/((1.0 — x**2)*atanh(x)). This increases from 1 at 0 
and becomes arbitrarily large near 1.0. 


Example of ATANH Called From FORTRAN 


Source Code: 


PROGRAM ATANH_EXAMPLE 


C ; 
x=0.5 
PRINT *, “The inverse hyperbolic tangent of x is:’ 
PRINT *, ATANH(x) 
END 
Output: 


The inverse hyperbolic tangent of x is: 
. 549306 1443341 
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ATAN2 


ATAN2 computes the inverse tangent function of the ratio of two arguments. It accepts 
two real arguments and returns a real result. 


The call-by-reference entry points are MLP$RATAN2 and ATAN2, and the call-by-value 
entry point is MLP$VATAN2. 


The ATAN2 vector math function is divided into three routines having three separate 
entry points defined as follows: 


-ATAN2(scalar,vector) = MLP$ATAN2SV 
ATAN2(vector,scalar) = MLP$ATAN2VS 
ATAN2(vector,vector) = MLP$ATAN2VV 


The input domain is the collection of all valid real pairs (x,y) such that both quantities 
are not equal to zero. The output range is included in the set of valid real quantities 
greater than —pi and less than or equal to pi. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
X is indefinite. 
y is indefinite. 
x and y are infinite. 
x and y are equal to zero. 
x/y is infinite (positive or negative) and y is not equal to zero. 
x is not equal to zero and y is infinite (positive or negative). 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite 
and y does not equal zero, it is invalid, and a diagnostic message is displayed. If the 
result is valid, it is returned to the calling program. 
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ATAN2 


The function ATAN2(y,x) is defined to be the angle, in the interval [-pi,pil, subtended 


at the origin by the point (x,y) and the first coordinate axis. 


The argument (y,x) is reduced to the first quadrant by the range reductions: 


atan2(y,x) = -atan2(-y,x), y < 0 
atan2(y,x) = pi - atan2(y,-x), x <0, y>0O 


The argument (y,x) is then reduced to the sector: 
(u,v): u>0, v<u, and v>0O 

by the range reduction: 
atan2(y,x) = pi/2 - atan2(x,y), x > 0 or y>0 


The routine calls ATAN to evaluate atan2(y,x) as arctan(y/x).” 


Vector Routine 

The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x and y are infinite. 


x and y are equal to zero. 


x/y is infinite (positive or negative) and y is not equal to zero. 


x is not equal to zero and y is infinite (positive or negative). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


2. Algorithm and Constants, Copyright 1970 by Krzysztof Frankowski, Computer Information and Control 


Science, University of Minnesota. 
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Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-4 shows a summary of these statistics. 


Effect of Argument Error 


If small errors e(x) and e(y) occur in x and y, respectively, the error in the result is 
given approximately by (y*e(x) -— x*e(y))/(x**2 + y**2). 
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Example of ATAN2 Called From FORTRAN 


Source Code: 


PROGRAM ATAN2_EXAMPLE 


C 
x=0.5 
y=0.6 
PRINT *, “The inverse tangent of the ratio of x,y is:’ 
PRINT *, ATAN2(x,y) 
END 
Output: 


The inverse tangent of the ratio of x,y is: 
. 694738276 1967 
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CABS 


CABS computes the absolute value of an argument. It accepts a complex argument and 
returns a real result. 


The call-by-reference entry points are MLP$RCABS and CABS, and the call-by-value 
entry point is MLP$VCABS. 


The input domain is the collection of all valid complex quantities z, where z = x + 
ity, and (x**2 + y**2)**.5 is a valid real quantity. The output range is included in the 
set of valid, nonnegative real quantities. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
call-by-reference routine. The result is checked. If the result is positive infinite, it is 
invalid, and a diagnostic message is displayed. If the result is valid, it is returned to 
the calling program. 


Call-By-Value Routine 
Let x + i*y be the argument. The algorithm used is: 


a. u = max([xl,lyl). 
v = min(Ixl,lyl). 


b. If u is zero, return zero to the calling program. 


c.f = v/u 
= 1.0 + r*¥*2 


where t = w**.5 = (1:0 + r**2)**.5 is computed inline using the same 
algorithm as used in SQRT. 


d. Return u*t to the calling program. 
Formulas used are: 
Ix + ity] = sqrt(x + ity) 


max({xl,lyl)*(1 + r**2)**.5 
= u*t 


where r = min(|x|,ly|)/max(|x|,ly]) 
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Error Analysis 


A group of 10,000 arguments was chosen randomly from the interval of complex 
-numbers ((-1.0,1.0],[-1.0,1.0]). The maximum relative error of these arguments was — 
found to be .1401E-13. 


Effect of Argument Error 


If a small error e(z) = e(x) + i*e(y) occurs in the argument z = x + i*y, the error in 
the result u is given by e(u) = (x*e(x) + y*e(y))/u. 


Example of CABS Called From FORTRAN 


Source Code: 


PROGRAM CABS_EXAMPLE 


C 
COMPLEX xi 
xi=(-40.0, -1) 
PRINT *, “The CABS of xi is:’ 
PRINT *, CABS(xi) 
END 
Output: 


The CABS of xi is: 
40 .01249804748 


NOTE 


CABS accepts a complex argument and returns a real result. 
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CCOS computes the complex cosine function. It accepts a complex argument and 
returns a complex result. 


The call-by-reference entry points are MLP$RCCOS and CCOS, the call-by-value entry 
point is MLP$VCCOS, and the vector entry point is MLP$CCOSV. 


The input domain is the collection of all valid complex quantities z, where z = x + 
i*y; |x| is less than 2**47 and |y| is less than 4095*log(2). The output range is included 
in the set of valid complex quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. The argument is invalid if: 

The real or imaginary part is indefinite. 

The real or imaginary part is infinite. 

The absolute value of the real part is greater than or equal to 2**47. 

The imaginary part is greater than or equal to 4095*log(2). 

The imaginary part is less than or equal to —4095*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 
Let x + i*y be the argument. The formula used for computation is: 
cos(x + ity) = cos(x)*cosh(y) - i*sin(x)*sinh(y) 


The routine evaluates COSSIN inline to simultaneously compute the sine and cosine of 
the real part of the argument. The routine evaluates HYPERB inline to simultaneously 
compute the hyperbolic sine and hyperbolic cosine of the imaginary part of the 
argument. See the descriptions of routines COSSIN and HYPERB in chapter 9, 
Auxiliary Routines, for detailed information. 


Vector Routine 
The argument is checked upon entry. The argument is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 
The absolute value of the real part is greater than or equal to 2**47. 
The imaginary part is greater than or equal to 4095*log(2). 
The imaginary part is less than or equal to —4095*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


See the descriptions of HYPERB and COSSIN in chapter 9, Auxiliary Routines, for 
details. If z = x + i*y is the argument, then the modulus of the error in the routine 
does not exceed: 1.276E-13 + 1.241E-13*exp(abs(y)). 


A group of 10,000 arguments was chosen randomly from the interval - 
((-1.0,1.0],[-1.0,1.0]). The maximum relative error of these arguments was found to be 
.7665E-13. 


Effect of Argument Error 


If a small error e(z) = e(x) + i*e(y) occurs in the argument z = x + i*y, the error in 
the result is given approximately by —sin(z)*e(z). 


Example of CCOS Called From FORTRAN 


Source Code: 


PROGRAM CCOS_EXAMPLE 


C 
COMPLEX xi 
xi=(-40.0, -1) 
PRINT *, “The complex cosine of xi is:’ 
PRINT *,CCOS(xi) | 
END 
Output: 


The complex cosine of xi is: 
(-1.029139207557 , -.875657875595 ) 
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CEXP computes the complex exponential function. It accepts a complex argument and 
returns a complex result. 


The call-by-reference entry points are MLP$RCEXP and CEXP, the call-by-value entry 
point is MLP$VCEXP, and the vector entry point is MLP$CEXPV. 


The input domain is the collection of all valid complex quantities z, where z = x + 
i*y; x is less than 4095*log(2) and x is greater than —4097*log(2), and ly| is less than 
2**47, The output range is included in the set of valid complex quantities. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 


The real part is greater than or equal to 4095*log(2) or less than or equal to 
-4097*log(2). 


The absolute value of the imaginary part is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 
Let x + i*y be the argument. The formula used for computation is: 
exp(x + i*y) = exp(x)*cos(y) + i*exp(x)*sin(y) 


The routine evaluates COSSIN inline to compute cos(y) and sin(y), and calls EXP to 
compute exp(x). 


Vector Routine 

The argument is checked upon entry. The argument is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 


The real part is greater than or equal to 4095*log(2) or less than or equal to 
-4097*log(2). 


. The absolute value of the imaginary part is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


See the descriptions of EXP in this chapter and COSSIN in chapter 9, Auxiliary 
Routines, for details. If z = x + i*y is the argument, then the modulus of the error in 
the routine does not exceed: 1.378E-13 + 1.378E-13*exp(abs(x)). If the real part of the 
argument is large, the error in the routine will be significant. 


The function CEXP was tested. A group of 10,000 arguments was chosen randomly 
from given intervals. Statistics on maximum relative error were observed. Table 8-5 
shows a summary of these statistics. 


Table 8-5. Relative Error of CEXP 
Interval Maximum 


({-1.0,1.0] [-1.0,1.0]) .5462E-13 
({ 1.0,.6700E + 03),{1.0,.11E + 15]) .9182E-13 


Effect of Argument Error 


If a small error e(z) = e(x) + i*e(y) occurs in the argument z = x + i*y, the error in 
the result w is given approximately by w*e(z). 


Example of CEXP Called From FORTRAN 


Source Code: 


PROGRAM CEXP_EXAMPLE 


C 
COMPLEX xi 
xi=(-4.0, -1) 
PRINT *, “The CEXP of xi is:’ 
PRINT *, CEXP(xi) 
END 
Output: 


The CEXP of xi is: 
(00989598 1925031, -.01541207869309) 
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CLOG computes the complex natural logarithm function. It accepts a complex argument 
and returns a complex result. 


The call-by-reference entry points are MLP$RCLOG and CLOG, the call-by-value entry 
point is MLP$VCLOG, and the vector entry point is MLP$CLOGV. 


The input domain is the collection of all valid complex quantities z, where z = x + 
ity, and (x**2 + y**2)**.5 is a valid, positive real quantity. The output range is 
included in the set of valid complex quantities z, such that the real part of z is a valid 
real quantity, and the imaginary part is greater than —pi and less than or equal to pi. 


Call-By-Reference Routine 

The argument is checked upon entry. The argument is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 
Both the real part and the imaginary part are zero. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
call-by-reference routine. The result is checked. If the result is infinite, it is invalid, 
and a diagnostic message is displayed. If the result is valid, it is returned to the 
calling program. 


Call-By-Value Routine 
The formula used for computation is: 
log(z) = log(IzI) + i*arg(z) 


where |z| is the modulus of z. The routine calls CABS to evaluate the absolute value of 
z and calls ALOG to compute the logarithm. Then the routine calls ATAN2 to evaluate 
the function arg(z). When z is nonzero, and in-range, arg(z) is in the interval [-pi,pil. 


Vector Routine 

The argument is checked upon entry. The argument is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 
Both the real part and the imaginary part are zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 
A group of 10,000 arguments was chosen randomly from the interval 


([-1.0,1.0],[-1.0,1.0]). The maximum relative error of these arguments was found to be 
.4346E-12. 
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Effect of Argument Error 


If a small error e(z) = e(x) + i*e(y) occurs in the argument z = x + i*y, the error in 
the result is given approximately by e(z)/z. 


Example of CLOG Called From FORTRAN 


Source Code: 


PROGRAM CLOG_EXAMPLE 


C 
COMPLEX xi 
xi=(-4.0, -1) 
PRINT *, “The CLOG of xi is:’ 
PRINT *, CLOG(xi) 
END 
Output: 


The CLOG of xi is: 
(1.41660667 2028 , -2. 8966 13990463) 


NOTE 


One of the real or imaginary parts for CLOG must be nonzero. 


60486513 H | Function Descriptions 8-41 


CONJG 


CONJG 


CONJG returns the conjugate of an argument. It accepts a complex argument and 
returns a complex result. 


The call-by-reference entry points are MLP$RCONJG and CONJG, and the 
call-by-value entry point is MLP$VCONJG. 


The input domain is the collection of all valid complex quantities. The output range is 
included in the set of valid complex quantities. 


Call-By-Reference Routine 


No errors are generated by CONJG. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The argument is returned with its imaginary part negated. 
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Example of CONJG Called From FORTRAN 


Source Code: 


PROGRAM CONJG_EXAMPLE 


EXTERNAL CONJG 

COMPLEX xi 

xi=(-40000.0, -1) 

PRINT *, “The conjugate of xi is:’ 
PRINT *, CONJG(xi) 

END 


Output: 


The conjugate of xi is: 
(-40000.,1.) 
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COS computes the cosine function. It accepts a real argument and returns a real 
result. 


The call-by-reference entry points are MLP$RCOS and COS, the call- by value entry 
point is MLP$VCOS, and the vector entry point is MLP$COSV. 


The input domain is the collection of all valid real quantities whose absolute value is 
less than 2**47. The output range is included in the set of valid real quantities in the 
interval [-1.0,1.0]. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


If x is valid, then COS(x) or SIN(x) is calculated by using the periodic properties of the 
cosine and sine functions to reduce the task to finding a cosine or sine of an 
equivalent angle y within [-pi/4, pi/4] as follows: 


If N + K is even 


then 
Z = sin(y) 
else 
Z = cos(y) 
If MOD(N + K, 4) is 0 or 1 (that is, the second last bit of N + K is even) 
then 
S=0 
else 
S = mask(1) 


where K is 0, 1, or 2 according to whether the SIN of a positive angle, the COS of 
any angle, or the SIN of a negative angle is to be calculated. N is the nearest integer 
to 2/pi*x, and y is the nearest single precision floating-point number to x - n*pi/2. The 
argument x is the absolute value of the angle. The desired SIN or COS is the 
exclusive or of S and Z. 


Once the angle has been reduced to the range [-pi/4, pi/4], the following 
approximations are used to calculate either the cosine or the sine of the angle, 
providing 48 bits of precision. 
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If the cosine of the angle is required, the approximation used is 
cosine(y) = 1. y*y*P(y*y) 

where y is the angle and P(w) is the quintic polynomial: 
P(w) = PO + P1*w) + P2*w**2 + P3 + w**3 + P4*wt*4 + P5*w**d 


such that P(y*y) is a minimax polynomial approximation to the function (1 - 
cos(y))/y**2. 


The coefficients are: 


P5 = -2.070062305624629462E-9 
P4 = 2.755636997406588778E-7 
P3 = -2.48015852 120642667 1E-5 
P2 = 1.388888888727866775E-3 
P1 = -4.1666666666664681 16E-2 
PO 5 . QO0000000000000000E-1 


If the sine of the angle is required, the approximation used is 
sine(y) = y - y*y*y*Q(y*y) 

where y is the angle and Q(w) is the quintic polynomial: 
Q(w) = QO + Qi*w + Qo*we+2 + Q3*w**3 + Q4*w**4 + Q5*w**5 


such that Q(y*y) is a minimax polynomial approximation to the function (y - 
sin(y))/y**3. 


The coefficients are: 


Q5 = -1.591814257033005283E-10 
Q4 = 2.505113204973767698E-8 
Q3 = -2.7557316 10365754733E-6 
Q2 = 1.984126983676 10091 1E-4 
Q1 = -8.333333333330950363E-3 
QO 1. 666666666666666463E-1 


Vector Routine 

The argument is checked upon entry. It is invalid if: | 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The function COS was tested against 4*COS(x/3)**3 - 3*COS(x/3). Groups of 2,000 
arguments were chosen randomly from the interval [.2199E +02,.2356E +02]. Statistics 
on relative error were observed: maximum relative error was .1404E-13, and root 
mean square relative error was .3245E-14. 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e*cos(x) for sin(x) and —e*sin(x) for cos(x). 


Example of COS Called From FORTRAN 


Source Code: 


PROGRAM COS_EXAMPLE 


Cc 
x=0.5 
PRINT *, “The cosine of x is:’ 
PRINT *, COS(x) 
END . 
Output: 


The cosine of x is: 
- 87758256 18904 
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Example of COS Called From Pascal 


Source Code: 


program COS_EXAMPLE (output); 
var x, y : REAL; 


begin 
x := 0.5; 
y := COS (x); 
writeln (’ The cosine of x is ’, y :1:13); 
end. 
Output: 


The cosine of x is 0.8775825618904 


60486513 H Function Descriptions 8-47 


COSD 


COSD 


COSD computes the cosine function for an argument in degrees. It accepts a real _ 
argument and returns a real result. 


The call-by-reference entry points are MLP$RCOSD and COSD, the call-by-value entry 
point is MLP$VCOSD, and the vector entry point is MLP$COSDV. 


The input domain is the collection of all valid real quantities whose absolute value is 
less than 2**47, The output range is included in the set of valid real quantities in the 
interval [-1.0,1.0]. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


The result is put in the interval [-45,45] by finding the nearest integer, n, to x/90, and 
subtracting n*90 from the argument. The reduced argument is then multiplied by 
pi/180. The appropriate sign is copied to the value of the appropriate function, sine or 
cosine, as determined by these identities: 


sin(x + 360 degrees) = sin(x) 
sin(x + 180 degrees) = -sin(x) 
sin(x + 90 degrees) = cos(x) 
sin(x - 90 degrees) = -cos(x) 
cos(x + 360 degrees) = cos(x) 
cos(x + 180 degrees) = -cos(x) 
cos(x + 90 degrees) = -sin(x) 
cos(x - 90 degrees) = sin(x) 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The reduction to (-45,+45) is exact; the constant pi/180 has relative error 1.37E-15, 
and multiplication by this constant has a relative error 5.33E-15, and a total error of 
6.7E-15. Since errors in the argument of SIN and COS contribute only pi/4 of their 
value to the result, the error due to the reduction and conversion is, at most, 5.26E-15 
plus the maximum error in SINCOS over (—pi/4, + pi/4). 


A group of 10,000 arguments was chosen at random from the interval [0,360]. The 
maximum relative error of these arguments was found to be .7105E-14 for COSD and 
.1403E-13 for SIND. 

Effect of Argument Error 


Errors in the argument x are amplified by x/tan(x) for SIND and x*tan(x) for COSD. 
These functions have a maximum value of pi/4 in the interval (-45,+45) but have 
poles at even (SIND) or odd (COSD) multiples of 90 degrees, and are large between 
multiples of 90 degrees if x is large. 


Example of COSD Called From FORTRAN 


Source Code: 


PROGRAM COSD_EXAMPLE © 


c 
x=180.0 
PRINT *, “The COSD of x is:’ 
PRINT *, COSD(x) 
END 
Output: 


The COSD of x is: 
=1: 
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COSH 


COSH computes the hyperbolic cosine function. It accepts a real argument and returns 
a real result. 


The call-by-reference entry points are MLP$RCOSH and COSH, the call-by-value entry 
point is MLP$VCOSH, and the vector entry point is MLP$COSHV. 


The input domain is the collection of all valid real quantities whose absolute value is 
less than 4095*log(2). The output range is included in the set of valid real quantities 
greater than or equal to 1.0. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than or equal to 4095*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 
The formula used to compute cosh(x) is: 
cosh(x) = (exp(x) + exp(-x))/2 


The routine calls EXP to compute exp(x) and computes 1.0/exp(x) to obtain exp(—x). 


Vector Routine 
The argument is checked upon entry. It is ‘valid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 4095*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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COSH 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-6 shows a summary of these statistics. 


Table 8-6. Relative Error of COSH 


Test Interval From 


COSH(x) against Taylor 0.0000E + 00 
series expansion of 
COSH(x) 


COSH(x) against .3000E+ 01 


e*(COSH(x + 1) + 
COSH(x - 1)) 


Effect of Argument Error 


Interval To 


.5000E + 00 


.2838E + 04 


Root Mean 
Maximum Square 


.1382E-13 .6875E-14 


.2296E-13 .8260E-14 


If a small error e occurs in the argument x, the resulting error in cosh(x) is given 


approximately by sinh(x)*e. 


Example of COSH Called From FORTRAN 


Source Code: 


PROGRAM COSH_EXAMPLE 


C 
x= 180.0 
PRINT *, “The COSH of x is:’ 
PRINT *, COSH(x) 
END 
Output: 


The COSH of x is: 
7.44692 1003909E+77 
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COTAN 


COTAN computes the trigonometric circular cotangent of an argument in radians. It 
accepts a real argument and returns a real result. 


The call-by-reference entry points are MLP$RCOTAN and COTAN, the call-by-value 
entry point is MLP$VCOTAN, and the vector entry point is MLP$COTANV. 


The input domain is the collection of all valid real quantities whose absolute value is 
greater than 0 and less than 2**47. The output range is included in the set of valid 
real quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is 0. 
Its absolute value is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine | 
The evaluation is reduced to the interval [-.5,.5] by using the identities: 
1. cotan(x) = cotan(x + k*pi/2), if k is even 
2. cotan(x) = -1.0/cotan(x + pi/2) 
in the form: 
3. cotan(x)=1/tan(x)=1/tan((pi/2)*(x*2/pi + k)), if k is even 
4. cotan(x)=1/tan(x)=tan((pi/2)*(x*2/pi + 1.0))/-1.0 


In effect, the original algorithm for TAN(x) is used to find COTAN(x). The result for 
COTAN(x) is the reciprocal of TAN(x). 


An approximation of tan(pi/2*y) is used. The argument is reduced to the interval 
[-.5,.5] by subtracting a multiple of pi/2 from x in double precision. 


The rational form is used to compute the tangent of the reduced value. The function 
tan((pi/2)*y) is approximated with a rational form (7th order odd)/(6th order even), 
which has minimax relative error in the interval [-.5,.5]. The rational form is 
normalized to make the last numerator coefficient 1 + e, where e is chosen to 
minimize rounding error in the leading coefficients. 


Identity 4 is used if the integer subtracted is odd. The result is negated and inverted 
by dividing -P/Q instead of Q/P. 
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Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is 0. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The function COTAN was tested against (COTAN(x/2)**2-1)/(2*COTAN(x/2)). Groups of 
2,000 arguments were chosen randomly from the interval (.1885E+02, .1963E+ 02). 
Statistics on relative error were observed: maximum relative error was .2297E-13, and 
root mean square relative error was .7847E-14. 


Effect of Argument Error 


For small errors in the argument x, the amplification of absolute error is sec(x)**2, 
and that of relative error is x/(sin(x)*cos(x)), which is at least 2x and can be arbitrarily 
large near a multiple of pi/2. 


Example of COTAN Called From FORTRAN 


Source Code: 


PROGRAM COTAN_EXAMPLE 


C 
x=180.0 
PRINT *, “The COTAN of x is:’ 
PRINT *, COTAN(x) 
END 
Output: 


The COTAN of x is: 
. 7469988 14414 
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CSIN computes the complex sine function. It accepts a complex argument and returns a 
complex result. 


The call-by-reference entry points are MLP$RCSIN and CSIN, the call-by-value entry 
point is MLP$VCSIN, and the vector entry point is MLP$CSINV. 


The input domain is the collection of all valid complex quantities z, where z = x + 
ity; |x | is less than 2**47, and ly | is less than 4095*log(2). The output range is 
included in the set of valid complex quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
The real or imaginary part is indefinite. | 
The real or imaginary part is infinite. 
The absolute value of the real part is greater than or equal to 2**47. 
The absolute value of the imaginary part is greater than or equal to 4095*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 
Let x + i*y be the argument. The formula used for computation is: 
sin(x + i*y) = sin(x)*cosh(y) + i*cos(x)*sinh(y) 


The routine evaluates COSSIN inline to simultaneously compute sine and cosine, and 
evaluates HYPERB inline to simultaneously compute hyperbolic sine and hyperbolic 
cosine. See the descriptions of routines COSSIN and HYPERB in chapter 9, Auxiliary 
Routines, for detailed information. 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 
The absolute value of the real part is greater than or equal to 2**47. 
The absolute value of the imaginary part is greater than or equal to 4095*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


If z = x + i*y is the argument, then the modulus of the error in the routine does not 
exceed: 1.276E-13 + 1.297E-13*exp(abs(y)). See the description of HYPERB and 
COSSIN for details in chapter 9, Auxiliary Routines. 


Effect of Argument Error 


If a:small error e(z) = e(x) + i*e(y) occurs in the argument z = x + i*y, the error in 
the result is given approximately by cos(z)*e(z). 


Example of CSIN Called From FORTRAN 


Source Code: 


PROGRAM CSIN_EXAMPLE 


C 
COMPLEX xi 
xi=(-40.0, -1) 
PRINT *, “The CSIN of xi is:’ 
PRINT *, CSIN(xi) 
END 
Output: 


The CSIN of xi is: 
(-1. 149769688682, .783786406 1402) 
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CSQRT computes the complex square root function that maps to the right half of the 
complex plane. It accepts a complex argument and returns a complex result. 


The call-by-reference entry points are MLP$RCSQRT and CSQRT, the call-by-value 
entry point is MLP$VCSQRT, and the vector entry point is MLP$CSQRTV. 


The input domain is the collection of all valid complex quantities z, where z = x + 
i*y, and (x**2 + y**2)**.5 + |x| is a valid real quantity. If the argument is zero, zero 
is returned. The output range is included in the set of valid complex quantities z such 
that the real part of z is nonnegative and the imaginary part of z is a valid complex 
quantity. . 


Call-By-Reference Routine 
The argument is checked upon entry. The argument is invalid if: 
The real or imaginary part is indefinite. 


The real or imaginary part is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
call-by-reference routine. The result is checked. If the result is positive infinite, it is 
invalid, and a diagnostic message is displayed. If the result is valid, it is returned to 
the calling program. 


For this computation, values returned by the routine will lie in the right half of the 
complex plane. 


Call-By-Value Routine 


Let x + i*y be the argument. The formulas used for computation are: 


(.5*(1xl + [(x,y)1))**.5 
.5*(y/u) 


u 
Vv 


If x is nonnegative, then csqrt(x,y) = u + i*v. If x is negative, then csqrt(x,y) = 
sign(y)*(v + i*u). 


The result of this routine always lies in the first or fourth quadrant of the complex 
plane. The routine takes complex quantities lying on the axis of the negative reals, to 
the axis of the positive imaginaries. 


Vector Routine 

The argument is checked upon entry. It is invalid if: 
The real or imaginary part is indefinite. 
The real or imaginary part is infinite. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The function CSQRT was tested. A group of 10,000 arguments was chosen randomly 
from given intervals. Statistics on maximum relative error were observed. Table 8-7 
shows a summary of these statistics. 


Table 8-7. Relative Error of CSQRT 


Interval Maximum 


([0,0],[100,100)) .1600E-13 


([0,0),[1.0E + 100,1.0E + 100]) .1499E-13 


Effect of Argument Error 
If a small error e(z) = e(x) + i*e(y) occurs in the argument z = x + i*y, the error in 


the result w = u + i*v is given approximately by e(z)/(2*w**0.5) = (e(x) + i*e(y))/2(u 
+ i*v)**0.5. | 


Example of CSQRT Called From FORTRAN 


Source Code: 


PROGRAM CSQRT_EXAMPLE 


C 
COMPLEX xi 
xi=(-40.0, -1) 
PRINT *, “The CSQRT of xi is: 
PRINT . CSQRT(xi) 
END 
Output: 


The CSQRT of xi is: 
( .07905076686887 , -6 .325049329748) 
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DABS computes the absolute value of an argument. It accepts a double precision 
argument and returns a double precision result. 


The call-by-reference entry points are MLP$RDABS and DABS, and the call-by-value 
entry point is MLP$VDABS. 


The input domain is the collection of all valid double precision quantities. The output 
range is included in the set of valid, nonnegative double precision quantities. 


Call-By-Reference Routine 


No errors are generated in DABS. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The argument is returned with the sign bits of both its upper and lower words forced 
positive. 
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Example of DABS Called From FORTRAN 


Source Code: 


Output: 


The DA 
1000.1 
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PROGRAM DABS_EXAMPLE 


EXTERNAL DABS 
DOUBLE PRECISION x 

x=- 1000. 1234d0 

PRINT *, “The DABS of x is:’ 
PRINT *, DABS(x) 

END 


BS of x is: 
234 


DABS 
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DACOS computes the inverse cosine function. It accepts a double precision argument - 
and returns a double precision result. 


The call-by-reference entry points are MLP$RDACOS and DACOS, and the call-by-value 
entry point is MLP$VDACOS. 


The input domain is the collection of all valid double precision quantities in the 
interval [-1.0,1.0]. The output range is included in the set of valid, nonnegative double 
precision quantities less than or equal to pi. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value exceeds 1.0. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


8-60 Math Library 60486513 H 


DACOS 


Call-By-Value Routine 


The following identities are used to move the interval of approximation to [0,sqrt(.5)]: 


arcsin(-x) = -arcsin(x) 

arccos(x) = pi/2-arcsin(x) 

arcsin(x) = arccos(sqrt(1.0 - x**2)), if x > 0 
arccos(x) = arcsin(sqrt(1.0 - x**2)), if x > 0 


The reduced value is called y. If y <= .09375, no further reduction is performed. If 
not, the closest entry to y in a table of values (z, arcsin(z), sqrt(1.0 - x**2), z = .14, 
.39, .52, .64) is found, and the following formula used is: 


arcsin(x) = arcsin(z) + arcsin(w) 


where w = x(sqrt(1.0 -— z**2) — z*sqrt(1.0 -— x**2). The value of w is in (-.0792, 
.0848). 


The arcsin of the reduced argument is then found using a 15th order odd polynomial 
with quotient: 


x + x**38(c(3) + x**2(c(5) + x**2(c(7) + x**2(c(11) + x**2(c(13) + 
x**2(c(15) + a/(b - x**2))))))) 


where all constants and arithmetic operations before c(11) are double precision and the 
rest are single precision. The addition of c(11) has the form single + single = double. 
The polynomial is derived from a minimax rational form (denominator is (b — x**2)) 

for which the critical points have been modified slightly to make c(11) fit in one word. 


To this value, arcsin(z) is added from a table if the last reduction above was done and 
the sum is conditionally negated. Then 0, —pi/2, + pi/2, or pi is added to complete the 
unfolding. 
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Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value exceeds 1.0. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The region of worst error is (.9895,.9966). In this region, the final addition is of 


quantities of almost equal magnitude and opposite sign, and cancellation of about one 
bit occurs. 


The function DACOS was tested against the Taylor series. Groups of 2,000 arguments 


were chosen randomly from given intervals. Statistics on relative error were observed. 
Table 8-8 shows a summary of these statistics. 


Table 8-8. Relative Error of DACOS 


Root Mean 
Interval From Interval To Maximum Square 
—.1250D +00 .1250D+00 .2794D-27 .2343D-27 
-.1000D+01 -.7500D+00 .3339D-27 .2853D-27 
.7500D + 00 .1000D+01 .7573D-28 .2257D-28 
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Effect of Argument Error 


If a small error e occurs in the argument x, the resulting error in DACOS is 
approximately —e/(1.0 — x**2)**.5. The amplification of the relative error is 
approximately x/(f(x)*(1.0 — x**2)**.5), where f(x) is DACOS. The error is attenuated 
for x > -.44 but can become serious near -1.0. If the argument is generated as 1.0 - 
y or y — 1.0, then the following identities can be used to get the full significance of y: 


asin(x) = acos(sqrt(1.0 - x**2)) 
acos(x) = asin(sgqrt(1.0 - x**2)) 
asin(-x) = -asin(x) 


acos(-x) = pi + asin(x) 
Example of DACOS Called From FORTRAN 


Source Code: 


PROGRAM DACOS_EXAMPLE 


c 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DACOS of x is:’ 
PRINT *, DACOS(x) 
END 
Output: 


The DACOS of x is: 
1.047 197551196597 746 1542 1446 
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DASIN 


DASIN computes the inverse sine function. It accepts a double precision argument and 
returns a double precision result. 


The call-by-reference entry points are MLP$RDASIN and DASIN, the call-by-value 
entry point is MLP$VDASIN, and the vector entry point is MLP$DASINV. 


The input domain is the collection of all valid double precision quantities in the 
interval [-1.0,1.0]. The output range is included in the set of valid double precision 
quantities in the interval [—pi/2,pi/2]. 


Call-By-Reference Routine 
Tihe-areamert is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value exceeds 1.0. 
If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 


the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 
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Call-By-Value Routine 


The following identities are used to move the interval of approximation to [0,sqrt(.5)): 


arcsin(-x) = -arcsin(x) 

arccos(x) = pi/2-arcsin(x) 

arcsin(x) = arccos(sqrt(1.0 - x**2)), if x > 0 
arccos(x) = arcsin(sqrt(1.0 - x**2)), if x >0 


The reduced value is called y. If y <= .09375, no further reduction is performed. If 
not, the closest entry to y in a table of values (z, arcsin(z), sqrt(1.0 - x**2), z = .14, 
.39, .52, .64) is found, and the formula used is: 


arcsin(x) = arcsin(z) + arcsin(w) 


where w = x(sqrt(1.0 — z**2) - z*sqrt(1.0 -— x**2). The value of w is in (-.0792, 
.0848). 


The arcsin of the reduced argument is then found using a 15th order odd polynomial 
with quotient: 


x + x**3(c(3) + x**2(C(5) + x**2(c(7) + x**2(c(11) + x**2(c(13) + 
x**2(c(15) + a/(b = x**2))))))) 


where all constants and arithmetic operations before c(11) are double precision and the 
rest are single precision. The addition of c(11) has the form single + single = double. 
The polynomial is derived from a minimax rational form (denominator is (b — x**2)) 

for which the critical points have been perturbed slightly to make c(11) fit in one word. 


To this value, arcsin(z) is added from a table if the last reduction above was done and 
the sum is conditionally negated. Then 0, —pi/2, + pi/2, or pi is added to complete the 
unfolding. 


60486513 H Function Descriptions 8-65 


DASIN 


Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value exceeds 1.0. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The region of worst error is (.09375,.1446). In this region, the final addition is of 
quantities of almost equal magnitude and opposite sign, and cancellation of about one 
bit occurs, the worst case being .1451-.0629. For DASIN, the polynomial range was 
extended to cover the region (.0821,.09375), where the worst error occurs. 


The function DASIN was tested against the Taylor series. Groups of 2,000 arguments 
were chosen randomly from given intervals. Statistics on relative error were observed. 
Table 8-9 shows a summary of these statistics. 


Table 8-9. Relative Error of DASIN 


: Root Mean 
Interval From Interval To Maximum Square 
-.1250D+00 .1250D+00 .1017D-27 .2246D-28 
.7500D + 00 .1000D+01 .4761D-27 .3575D-27 
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DASIN 


Effect of Argument Error 


If a small error e occurs in the argument x, the resulting errors in DASIN are 
approximately e/(1 -— x**2)**.5. The amplification of the relative error is approximately 
x/(f(x)*#(1 - x**2)**.5), where f(x) is DASIN. The error is attenuated for abs(x) < .75 
but can become serious near -1.0 or +1.0. If the argument is generated as 1 - y or y 


- 1, then the 


asin(x) = 
acos(x) = 
asin(-x) = 
acos(-x) = 


following identities can be used to get the full significance of y: 


acos(sqrt(1.0 - x**2)) 
asin(sqrt(1.0 - x**2)) 
-asin(x) 

pi + asin(x) 


Example of DASIN Called From FORTRAN 


Source Code: 


PROGRAM DASIN_EXAMPLE 


DOUBLE PRECISION x 
x=0.5d0 

PRINT *, “The DASIN of x is:’ 
PRINT *, DASIN(x) 


END 


Output: 


The DASIN of x is: 
.523598775598298873077 107231 
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DATAN 


DATAN computes the inverse tangent function. It accepts a double precision argument 


and returns a double precision result. 


The call-by-reference entry points are MLP$RDATAN and DATAN, the call-by-value 
entry point is MLP$VDATAN, and the vector entry point is MLP$DATANV. 


The input domain is the collection of all valid double precision quantities. The output 


range is included in the set of valid double precision quantities in the 


[-pi/2,pi/2]. 


Call-By-Reference Routine 


The argument is checked upon entry. It is invalid if it is indefinite. 


interval 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


Register pair (X4,X5) holds the absolute value of the argument. 


B4 = (X9) = 


sign mask for the argument. (B4 holds a mask for the result’s sign.) 


If |x| < 1.0, then: 


B3 = 
B7 = 


Branch to DATCOM at label DIN to complete processing. 


(XA) 
(XB) 


0. (B7 will hold the closest multiple of pi/2 to the absolute 
value of the result.) 


If |x| = 1.0, then: 


B3 = (XA) 
B7 = (XB) 
Branch to 


DATCOM at label DATCOM to complete processing. 


1 in high order bit. 


1.0. 


At labels DATCOM and DTN: 


(x9) 
(XA) 
(XB) 


B4 
B3 
B7 


mask MS = sign of final result. 


mask MI. 


closest multiple of pi/2 to the absolute value of the result. 


At label DATCOM: 


Register pair (X7,X8) 
Register pair (X4,X5) 


At label DTN: 


Register pair (X7,X8) 
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DATAN 


Label ATNU is the start of an 18-word table containing atan(n/8) (0 = n = 8) in 


double precision. Label DATCOM corresponds to 
step b. 


Constants 


= -1 


. 333 
. 199 
. 142 
111 
.090 
.001 
-085 
. 133 


333 
999 
857 
111 
909 
351 
666 
579 


333 
999 
142 
111 
0390 
201 
743 
709 


333 
999 
857 
111 
908 
845 
757 
202 


used in the algorithm 


333 
999 
142 
109 
247 
778 
593 
919 


are: 


333 333 333 285 915 
999 999 673 046 526 
856 280 180 055 289 
972 932 035 508 119 
503 

152 

089 

6 


step a, and label DTN corresponds to 


where d3, d5, d7, and d9 are double precision constants, and cll, cl13, a, and b are 
real constants. Arithmetic operations with d subscripts are done in double precision, 
and operations with u subscripts are done in single precision. For example, d3 +(d) q 
indicates that the addition is in double precision. Boolean operations have B subscripts. 


The algorithm used is: 


a. 


b. 


Le 


DQ = 


DU/DV computed in double precision. 


(DQ = DA-DU at DTN) 


n= 


(Note that 0 < DQ < 1.0.) 


nearest multiple of 1/8 to DQ. 


If n = 0, go to step f. 


i=] 
> 
il 


N 
it 


(DQ - n/8)/(1.0 + n/8*DA), computed in double precision. 


0 
0 


If (DA)(u) = 0, go to step i. 


XX*(d)(d3 +(d) XX*(d)(d5 +(d) XX*(d) (d7 +(d) XxX*(d)(d9 +(d) 


XX*(d)(d11 +(d) XX*(u)(c13 +(u) a/(b -(u) XX))))))) 


DC*DA 


0 DB = ATN(9)*2*(XB) 


XX = DA(u)*DA(u) 
DC = 

w = DA +(d) 

DB = 0 

If (XB)not= 
BBAR = 

CBAR 


(B7*pi/2) - (B)B3 (upper and lower) 


= BBAR + (D)ATN(n/8). ATN(n/8) is obtained as a double precision 
quantity from a table of precomputed values. 


Result = (CBAR + (D) w) - (B) (B3 - (B)B4). 


At the end of processing, register pair (XE,XF) contains the DATAN result. 
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DATAN 


Vector Routine 
The argument is checked upon entry. It is invalid if it is indefinite. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 
The maximum absolute value of relative error in the algorithm is 1.622E-29. 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-10 shows a summary of these statistics. 


Table 8-10. Relative Error of DATAN 


Root Mean 
Test Interval From Interval To Maximum Square 
DATAN(x) against -.6250D-01 .6250D-01 .2556D-28 .1343D-28 
truncated Taylor series 
2*DATAN(x) against .2697D + 00 .4142D+00 .4821D-28 .2027D-28 
DATAN(2x/(1 - x*x)) .4142D +00 .1000D+01 .5992D-28 .2449D-28 
DATAN(x) against .6250D-01 .2679D+00 .3388D-28 .1557D-28 


DATAN(1/16) + 
DATAN((x — 1/16)(1 + 
x/16)) 


Total Error 


Most of the errors can be traced back to errors in double precision addition. 
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DATAN 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given by e/(1.0 
+ x**2), 


Example of DATAN Called From FORTRAN 


Source Code: 


PROGRAM DATAN_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DATAN of x is:’ 
PRINT *, DATAN(x) 
END 
Output: 


The DATAN of x is: 
-463647609000806 1162 14256231 
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DATAN2 


DATAN2 computes the inverse tangent function of the ratio of two arguments. It 
accepts two double precision arguments and returns a double precision result. 


The call-by-reference entry points are MLP$RDATAN2 and DATAN2, and the 
call-by-value entry point is MLP$VDATAN2. 


The DATAN2 vector math function is divided into three routines having three separate 
entry points defined as follows: 


DTAN2(scalar,vector) = MLP$DATAN2SV 
DTAN2(vector,scalar) = MLP$DATAN2VS 
DTAN2(vector,vector) = MLP$DATAN2VV 


The input domain is the collection of all valid double precision pairs (x,y) such that 
both quantities are not zero. The output range is included in the set of double precision 
quantities greater than -pi and less than or equal to pi. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x and y are infinite. 
x and y are equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the calling program. 


Call-By-Value Routine 


Register pair (X4,X5) holds the absolute value of the first argument. Register pair 
(X7,X8) holds the absolute value of the second argument. 


B4 = (X9) = sign mask of the first word of the first argument. 

B3 = (XA) = complement of the sign mask of the first word of the second 
argument. 

B7 = (XB) = closest multiple of pi/2 to the result value. 


If (X4) > (X7), then: 


B7 = (XB) = 1.0. 
Branch to tabel DATCOM to complete processing. 
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If (X4) = (X7), then: 


Exchange (X7) and (X4) and (X8) and (X5). 
Complement contents of B3. 
B7 = (XB) = 0, if the first word of the second argument is positive. 
B7 = (XB) = 2, if the first word of the second argument is negative. 
Branch to label DATCOM to compiete processing. 


At label DATCOM: 


(X9) = B4 
(XA) = B3 
(XB) = B7 


Register pair (X7,X8) = DU 
Register pair (X4,X5) 


mask MS = sign of the final result. 


mask 


MI. 


DATAN2 


closest multiple of pi/2 to the absolute value of the result. 


At label DATCOM10: 


Register pair (X7,X8) 


DV 


il 


DQ 


smaller of DU and DB 


larger of DU and DV 


= min(x,y). 
= max(x,y). 


DU/DV, which is < 1.0. 


ATNU is the start of an 18-word table containing atan(n/8) (0 = n <= 8) in double 
precision. Label DATCOM corresponds to step a (on the following page). 


Constants used in the algorithm are: 


d3 = - 


.333 
. 199 
- 142 
111 
.090 
.001 
-085 
. 133 


333 
999 
857 
111 
909 
351 
666 
579 


333 
999 
142 
111 
090 
201 
743 
709 


333 
999 
857 
111 
908 
845 
757 
202 


333 
999 
142 
109 
247 
778 
593 
919 


333 333 333 285 915 
999 999 673 046 526 
856 280 180 055 289 
972 932 035 508 119 
503 

152 

089 

6 


where d3, d5, d7, and d9 are double precision constants, and cll, c13, a, and b are 
real constants. Arithmetic operations with d subscripts are done in double precision, 
and operations with u subscripts are done in single precision. For example, d3 +(d) q 
indicates that the addition is in double precision. Boolean operations have B subscripts. 
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DATAN2 


The algorithm used is: 
a. DQ = DU/DV in double precision. 
b. If both DU and DV are zero, error exit occurs. 
c. n= nearest multiple of 1/8 to DQ. 
d. If n = 0, go to step f. 
e. DA = (DQ - n/8)/(1 + n/8*DA), computed in double precision. 
f. Z =0 
DC = 0 
If (DA)(u) = 0, go to step i. 
g. XX = DA(u)*DA(u) 
DC = XX*(d)(d3 +(d) XX*(d)(d5 +(d) XXxX*(d) (d7 +(d) XX*(d)(d9 +(d) 
XX*(d)(d11 +(d) XxX*(u)(c13 +(u) a/(b -(u) XX))))))) 


h. w= DA + (d) DC*DA 


i. DB=0 
If (XB) not= 0 DB = ATN(9)*2*(XB) 


j. BBAR = (B7*pi/2) - (B)B3 (upper and lower) 


k. CBAR = BBAR + (D)ATN(n/8). ATN(n/8) is obtained as a double precision 
quantity from a table of precomputed values. 


1. Result = (CBAR + (D) w) - (B) (B3 - (B)B4). 


At the end of processing, register pair (XE,XF) contains DATAN2 result. 


Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is infinite. 
x and y are infinite. 
x and y are equal to 0. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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DATAN2 


Error Analysis 


The maximum absolute value of relative error in the algorithm is 1.622E-29. 


Effect of Argument Error 


If small errors e(x) and e(y) occur in the arguments x and y, respectively, the error in 
the result is given approximately by: 


(x*e(y) - y*e(x))/(x**2 + y**2) 
Example of DATAN2 Called From FORTRAN 


Source Code: 


PROGRAM DATAN2_EXAMPLE 


DOUBLE PRECISION x, y 

x=0.5d0 

y=5.0d0 

PRINT *, “The DATAN2 of x,y is:’ 
PRINT *, DATAN2(x,y) 

END 


Output: 


The DATAN2 of x,y is: 
.09966865249 1162027378446 1199 
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DCOS 


DCOS computes the cosine function. It accepts a double precision argument and returns 
a double precision result. 


The call-by-reference entry points are MLP$RDCOS and DCOS, the call-by-value entry 
point is MLP$VDCOS, and the vector entry point is MLP$DCOSV. 


The input domain is the collection of all valid double precision quantities whose 
absolute value is less than 2**47. The output range is included in the set of valid 
double precision quantities in the interval [-1.0,1.0]. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 


Its absolute value is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


Upon entry, the argument x is made positive and is multiplied by 2/pi in double 
precision, and the nearest integer n to x*2/pi is computed. At this stage, x*2/pi is 
checked to see that it does not exceed 2**47. If it does, a diagnostic message is 
returned. Otherwise, y = x — n*pi/2 is computed in double precision as the reduced 
argument, and y is in the interval [—pi/4,pi/4]. The value of mod(n,4), the entry point 
called, and the original sign of x determine whether a sine polynomial approximation 
p(x) or a cosine polynomial approximation q(x) is to be used. A flag is set to indicate 
the sign of the final result. 


For x in the interval [—pi/4,pi/4], the sine polynomial approximation is: 


p(x) = a(1)x + a(3)x**38 + a(5)x**5 + a(7)x**7 + a(9)x**9 + a(11)x**11 + 
a(13)x**13** + a(15)x**15 + a(17)x**17 + a(19)x**19 + a(21)x**21 


and the cosine polynomial approximation is: 


q(x) = b(0) + b(2)x**2 + b(4)x**4 + b(6)x**6 + bD(8)x**8 + D(10)x**10 + 
b(12)x**12 + b(14)x**14 + b(16)x**16 + b(18)x**18 + b(20)x**20 
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The coefficients are: 


a(1) 
a(3) 
a(5) 
a(7) 
a(9) 
a(11) 
a(13) 


a(15) = 


a(17) 


a(19) = 
a(21) = 


b(0) 
b(2) 
b(4) 
b(6) 
b(8) 
b( 10) 
b( 12) 
b( 14) 
b( 16) 
b( 18) 
b(20) 


.999 
. 166 
. 833 
. 198 
-275 
. 250 
. 160 
. 764 
.281 
.822 
. 194 
.999 
.499 
-416 
. 138 
- 248 
275 
. 208 
114 
-477 
. 156 
-408 


999 
666 
333 
412 
573 
521 
590 
716 
145 
042 
362 
999 
999 
666 
888 
015 
573 
767 
707 
947 
187 
023 


999 
666 
333 
698 
192 
083 
438 
373 
706 
461 
013 
999 
999 
666 
888 
873 
192 
569 
455 
696 
668 
947 


999 
666 
333 
412 
239 
854 
368 
079 
930 
317 
130 
999 
999 
666 
888 
015 
239 
878 
958 
822 
345 
777 


999 
666 
333 
698 
858 
417 
179 
886 


999 
666 
333 
412 
906 
101 
417 
084 


999 
666 
333 
698 
394 
138 
271 
755 


018*10**-14 
923*10**-17 
224*10**-19 


999 
999 
666 
888 
873 
858 
619 
584 
393 


999 
999 
666 
888 
015 
775 
214 
315 
115 


999 
999 
666 
888 
699 
558 
898 
495 
933 


316* 10**-15 
860* 10**-18 


999 
666 
332 
291 
406 
076 
194 
348 


999 
999 
666 
755 
922 
669 
747 
950 
106 


999 
666 
709 
344 
844 
473 
064 
748 


999 
999 
139 
436 
737 
957 
461 
765 
267 


99 

52 
57*10**=2 
78* 10**-3 
01*10**-5 
5*10**=7 
61*10**-9 
91*10**-12 


99 

19 

02 

28* 10**-2 

30* 10**-4 

11*10**-6 

35*10**-8 

75*10**-10 
21*10**-13 


DCOS 


These polynomials are evaluated from right to left in double precision. The sign flag is 
used to give the result the correct sign before returning to the calling program. 


Vector Routine 


The argument is checked upon entry. It is invalid if: 


It is indefinite. 


It is infinite. 


Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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DCOS 


Error Analysis 


The maximum absolute value of the error of approximation of p(x) to sin(x) over 
(-pi/4,pi/4) is .2570E-28, and of q(x) to cos(x) is .3786E-28. 


The function DCOS was tested against 4*DCOS(x/3)**3 - 3*DCOS(x/3). Groups of 2,000 
arguments were chosen randomly from the interval [.2199D + 02,.2356D+02]. Statistics 
on relative error were observed: maximum relative error was .2057D-23; root mean 
square relative error was .4606D-25. 


Effect of Argument Error 
If a small error e occurs in the argument x, the resulting error in cos is given 


approximately by -e*sin(x). If the error e becomes significant, the addition formulas for 
sin and cos should be used to compute the error in the result. 
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Example of DCOS Called From FORTRAN 


Source Code: 


PROGRAM DCOS_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DCOS of x is:’ 
PRINT *, DCOS(x) 
END 
Output: 


The DCOS of x is: 
. 87758256 18903727 16116281583 
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DCOSH 


DCOSH computes the hyperbolic cosine function. It accepts a double precision argument 
and returns a double precision result. 


The call-by-reference entry points are MLP$RDCOSH and DCOSH, the call-by-value 
entry point is MLP$VDCOSH, and the vector entry point is MLP$DCOSHV. 


The input domain is the collection of all valid double precision quantities whose 
absolute value is less than 4095*log(2). The output range is included in the set of valid 
double precision quantities greater than or equal to 1.0. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than or equal to 4095*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument pair is 
valid, the call-by-value routine is called, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 

The formulas used for computation are: 
u = exp(x)*.5 
v = exp(-x)*.5 


cosh(x) =ut+vyv 


The routine calls DEXP to compute exp(x). 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 4095*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


DCOSH 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-11 shows a summary of these statistics. 


Table 8-11. Relative Error of DCOSH 


Test Interval From 
DCOSH(x) against 0.0000D + 00 
Taylor series expansion 

of DCOSH(x) 

DCOSH(x) against .3000D+01 


c*(DCOSH(x + 1) + 
DCOSH(x - 1)) 


Effect of Argument Error 


Root Mean 
Interval To Maximum Square 
.5000D+00 .2524D-28 .1739D-28 
4548D-28 


.2838D +04 .1023D-27 


If a small error e occurs in the argument x, the error in cosh(x) is approximately 


sinh(x)*e. 


Example of DCOSH Called From FORTRAN 


Source Code: 


PROGRAM DCOSH_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DCOSH of x is:’ 
PRINT *, DCOSH(x) 
END 
Output: 


The DCOSH of x is: 
1. 1276259652063807 8522622516 
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DDIM 


DDIM computes the positive difference between two arguments. It accepts two double 
precision arguments and returns a double precision result. 


The call-by-reference entry points are MLP$RDDIM and DDIM, and the call-by-value 
entry point is MLP$VDDIM. 


The input domain is the collection of all valid double precision pairs (x,y) such that x 
- y is a valid double precision quantity. The output range is included in the set of 
valid, nonnegative double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x - y is infinite. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is branched to, and the result of the computation is 
returned to the calling program. 


Call-By-Value Routine 


Upon entry, the difference between the two arguments is formed, and the sign bit of 
the difference is extended across another word to form.a mask. The boolean product of 
the mask’s complement and the upper and lower word of the difference is formed. 


Given arguments (x,y): 


result = x - y if x >y 
result = 0 if x <y. 
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DDIM 


Example of DDIM Called From FORTRAN 


Source Code: 


PROGRAM DDIM_EXAMPLE 


EXTERNAL DDIM 

DOUBLE PRECISION x,y 

x=999999 .99d0 

y=99 .0d0 

PRINT *, “The DDIM of x,y is:’ 
PRINT *,DDIM(x,y) 

END 


Output: 


The DDIM of x,y is: 
999900 .99 
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DEXP 


DEXP computes the exponential function. It accepts a double precision argument and 
returns a double precision result. 


The call-by-reference entry points are MLP$RDEXP and DEXP, the call-by-value entry 
point is MLP$VDEXP, and the vector entry point is MLP$DEXPV. 


The input domain is the collection of all valid double precision quantities whose value 
is greater than or equal to —4097*log(2) and less than or equal to 4095*log(2). The 
output range is included in the set of valid double precision quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

It is greater than 4095*log(2). 

It is less than -—4097*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument pair is 
valid, the call-by-value routine is called, and the result of the computation is returned 
to the call-by-reference routine. The result is checked. If the result is infinite, it is 
invalid, and a diagnostic message is displayed. If the result is valid, it is returned to 
the calling program. 


Call-By-Value Routine 


The argument reduction performed is: 


X = argument 
y = x - n*log(2) 


where y = is in [-1/2 log(2), 1/2 log(2)] and n is an integer. 


Constants used in the algorithm are: 


1.0/109(2) 

log(2) (in double precision) 

d3 = .166 666 666 666 666 666 666 666 666 709 

dS = .833 333 333 333 333 333 333 331 234 953*10**-2 
d7 = .198 412 698 412 698 412 700 466 386 658*10**-3 
d9 = .275 573 192 239 858 897 408 325 908 796*10**-5 
pe = -.474 970 880 178 988*10**-10 

pa = -566 228 284 957 811*10**-7 

pb = 272.110 632 903 710 

c11 = -250 521 083 854 439*10**-7 


Arithmetic operations with d subscripts are done in double precision, and operations 
with u subscripts are done in single precision. For example, d3 +(d) q indicates that 
the addition is in double precision. An operand with a u or | subscript denotes the first 
or second word, respectively, of the double precision pair of words containing the 
operand. 
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DEXP 


On input, the argument is in register pair X2-X3, and on output, the result is in 


register pair XE-XF. 


The algorithm used is: 


a. xX = argument. 
b. If x not= 0, 
n = 
y = x - n*log(2). 
c. qe= (y)(u)*(u)(y)(u) 
d. pe= 
e. s = (y)(u) +(d) (y)(u)*(d)p 
f. Compute hm = 
hi = 
hj = hi + hi 
hk = 2*(1.0 + hj) 
hl = 
hm = 
g. DS = 
h. DC = 
double precision. 
i. DX = DS + DC 
j. Clean up DS, DC, DX 
Register pair XA-XB 
Register pair X8-X9 
Register pair X4-X5 
k. 
1. Return. 
60486513 H 


If x = 0, set DEXP = 1.0. Return. 


nearest integer to x/log(2),- 


Then y is in [-1/2*10g9(2), 1/2*10g(2)]. 


q*(d)(d3 +(d) g*(d)(d5 +(d) q*(d)(d7 +(d) q*(d)(d9 +(d) 
aq*(d)(ci1 +(d) q*(d)(pa/(pb - q) + pc)))))) 


sart(1.0 + s**2). 


3*q + ((s)(u))**2 in real. 


(Cy) (u) *(u) Cy) (u) - hj)/hk - hi 
hj +(u) (hk -(u) h1)*(u)(h1/hk) 
(hm now carries cosh - 1.0 in single precision.) 


s + (a)(((y)C1) + Cr) Cy) (1) *Cudhm) + (r) (Cs) (1) + 
(r)((y)(u)* (1) (p)(u) + (r)(y)(u)*(r) (p) 1) ))) 


(DS now contains sinh(y) in double precision.) 


hm +(d) (DS*DS - 2*hm - hm*hm)/(2(1.0 + hm)) computed in 


with 


DS 
DC 
DX 


(X7) =n. 


sinh(y). 
cosh(y) - 1.0. 
exp(y). 


Increase the exponents of exp(y) by n. 
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DEXP 


Vector Routine 


The argument is checked upon entry. It is invalid if: 


It is indefinite. 

It is infinite. 

It is greater than 4095*log(2). 
It is less than —4097*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-12 shows a summary of these statistics. 


Table 8-12. Relative Error of DEXP 


Test Interval From 


DEXP(x - 2.8125) -.3466D+01 
against DEXP(x) / 
DEXP(2.8125) 


DEXP(x — .0625) -.2841D+00 
against DEXP(x) / 
DEXP(.0625) 


DEXP(x - 2.8125) .6931D +01 


against DEXP(x) / 
DEXP(2.8125) 


Effect of Argument Error 


Interval To 


-.2772D + 04 


.3466D + 00 


.2838D + 04 


Maximum 


.9240D-28 


.6449D-28 


.9262D-28 


Root Mean 
Square 


.2956D-28 


.1680D-28 


.2907D-28 


If a small error e occurs in the argument the error in the result y is given © 


approximately by y*e. 
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Example of DEXP Called From FORTRAN 


Source Code: 


PROGRAM DEXP_EXAMPLE 


C 
. DOUBLE PRECISION x 
x=3 .0d0 
PRINT *, “The DEXP of x is:’ 
PRINT *,DEXP(x) 
END 
Output: 


The DEXP of x is: 
20 .085536923 187667 7409285297 
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DEXP 
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DIM 


DIM computes the positive difference between two arguments. It accepts two real 
arguments and returns a real result. 


The call-by-reference entry points are MLP$RDIM and DIM, and the call-by-value entry 
point is MLP$VDIM. 


“The input domain is the collection of all valid real quantities (x,y), such that x - y is 
a valid real quantity. The output range is included in the set of valid real quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. | 
y is indefinite. 
x is infinite. 
y is infinite. 
x — y is infinite. 
If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 


is valid, the call-by-value routine is branched to, and the result of the computation is 
returned to the calling program. 


Call-By-Value Routine 

Upon entry, the difference between the two arguments is formed, and the sign bit is 
extended across another word to form a mask. The boolean product of the mask’s 
complement and the difference is formed. 


Given arguments (x,y): 


result = x - yif x > y 
result = 0 if x <y 


Example of DIM Called From FORTRAN 


Source Code: 


PROGRAM DIM_EXAMPLE 


C 
EXTERNAL DIM 
x=30.0 
y=3000 .0 
PRINT *, “The positive difference between y and x is: °’, DIM(y,x) 
END 
Output: 


The positive difference between y and x is: 2970. 
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DINT 


DINT returns the integer part of an argument after truncation. It accepts a double 
precision argument and returns a double precision result. 


The call-by-reference entry points are MLP$RDINT and DINT, and the call-by-value 
entry point is MLP$VDINT. 


The input domain for this function is the collection of all valid double precision 
quantities. The output range is included in the set of valid double precision quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


The argument is added to a special floating-point zero with an exponent value that 
forces the argument’s fraction bits to be shifted off when it is added to the argument. 
The result is returned. 


Example of DINT Called From FORTRAN 


Source Code: 


PROGRAM DINT_EXAMPLE 


EXTERNAL DINT 

DOUBLE PRECISION x 

xX=333 .333d0 

PRINT *, “The integer part of double precision x is:’ 
PRINT *,DINT(x) 

END 


Output: 


The integer part of double precision x is: 
333. 
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DLOG 


DLOG computes the natural logarithm function. It accepts a double precision argument 
and returns a double precision result. 


The call-by-reference entry points are MLP$RDLOG and DLOG, the call-by-value entry 
point is MLP$VDLOG, and the vector entry point is MLP$DLOGV. 


The input domain for this function is the collection of all valid, positive double 
precision quantities. The output range is included in the set of double precision 
quantities whose absolute value is less than 4095*log(2). 


Call-By-Reference Routine 
The argument is checked upon entry. The argument is invalid if: 
It is indefinite. 
It is infinite. 
It is equal to zero. 
It is negative. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result. of the computation is returned to the 
calling program. 


Call-By-Value Routine 


Upon entry, the argument x is put into the form x = 2**k*w, where k is an integer, 
and 2**-1/2 = w <= 2**1/2. Then log(x) is computed from: 


log(x) = k*log(2) + log(w) 


and k*log(2) is computed in double precision. A polynomial approximation u is 
evaluated in single precision using: 


u = c(1)*t + c(3)*t**3 + c(5)*t**5 + c(7)*t**7 


where t = (w - 1.0)/(1.0 + w) 
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DLOG 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is equal to zero. 
It is negative. 
See Vector Error Handling in chapter 7, Vector Processing, for further information. 
The coefficients c(1), c(3), c(5), and c(7) are: 


c(1) = 1.999 999 993 734 000 


c(3) = .666 669 486 638 944 
c(5) = .399 657 811 051 126 
c(7) = .301 005 922 238 712 


This approximates log with a relative error of absolute value at most 3.133*10**-8 
over (2**—1/2,2**-1/2). Newton’s rule for finding roots’ is then applied in two stages to 
the function exp(x) - w to yield the final approximation to log(w). The two stages are 
algebraically combined to yield the final approximation v: 


v =u - (1.0 - x*exp(-u)) - (1.0 - x*exp(-u - (1.0 - x*exp(-u)))) 


z is made to be less than 1.0 by writing z = 1.0 - x*exp(—u), and v is computed 
using: 


v= u- 2(u) - 2(1) - (z(u))**2*(.5 + 2(u)/3) 


where z = z(u) + 2(1). This formula is obtained by neglecting terms that are not 
significant for double precision; exp(—u) is evaluated in double precision by the 
polynomial of degree 17. If entry was made at MLP$VDLOGI1O0, after k*log(2) + log(w) 
has been evaluated, the result is multiplied by log(e) base 10 in double precision. 


8. For a discussion of Newton’s rule for finding roots, refer to any calculus text (for example, Calculus and 
Analytic Geometry by G. B. Thomas). 


60486513 H | Function Descriptions 8-91 


DLOG 


Error Analysis 


The maximum absolute value of the error of approximation of the algorithm to log(x) is 
1.555E-29 over the interval (2**(—.5),2**.5). 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-13 shows a summary of these statistics. 


Table 8-18. Relative Error of DLOG 


Root Mean 
Test Interval From Interval To Maximum Square 
DLOG(x*x) against .1600D + 02 .2400D+03 .4479D-28 .1528D-28 
2*DLOG(x) 
DLOG(x) against .7071D +00 .9375D+00 .9041D-27 .1478D-27 
DLOG(17x/16) - 
_DLOG(17/16) 
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Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/x. 


Example of DLOG Called From FORTRAN. 


Source Code: 


PROGRAM DLOG_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The natural logarithm of x is:’ 
PRINT *, DLOG(x) 
end 
Output: 


The natural logarithm of x is: 
- .693147 1805599453094 17232121 
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DLOG10 


DLOG10 computes the common logarithm function. It accepts a double precision 
argument and returns a double precision result. 


The call-by-reference entry points are MLP$RDLOGI0 and DLOGIO, the call-by-value 
entry point is MLP$VDLOG10, and the vector entry point is MLP$DLOGI0V. 


The input domain for this function is the collection of all valid, positive double 
precision quantities. The output range is included in the set of double precision 
quantities whose absolute value is less than 4095*log(2) base 10. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is equal to zero. 
It is negative. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 
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Call-By-Value Routine 


Upon entry, the argument x is put into the form x = 2**k*w, where k is an integer, 
and 2**~-1/2 = w = 2**1/2. Then log(x) is computed from: 


log(x) = k*log(2) + log(w) 


and k*log(2) is computed in double precision. A polynomial approximation u is 
evaluated in single precision using: 


u = c(1)*t + c(3)*t**3 + c(5)*t**5 + c(7)*t**7 
where t = (w — 1.0)/(1.0 + w) 


The coefficients c(1), c(3), c(5), and c(7) are: 


c(1) = 1.999 999 993 734 000 
c(3) = .666 669 486 638 944 
c(5) = .399 657 811 051 126 
c(7) = .301 005 922 238 712 


This approximates log with a relative error absolute value at most 3.133*10**-8 over 
(2**—-1/2,2**-1/2). Newton’s rule for finding roots* is then applied in two stages to the 
function exp(x) -— w to yield the final approximation to log(w). The two stages are 
algebraically combined to yield the final approximation v: 


v =u - (1.0 - x*exp(-u)) - (1.0 - x*exp(-u - (1.0 - x*exp(-u)))) 


z is made to be less than 1.0 by writing z = 1.0 — x*exp(-u), and v is computed 
using: 


v= u- 2(u) - 2(1) - (2z(u))**2*(.5 + 2(u)/3) 


where z = z(u) + 2(l). This formula is obtained by neglecting terms that are not 
significant for double precision; exp(—u) is evaluated in double precision by the 
polynomial of degree 17. If entry was made at MLP$VDLOG10, after k*log(2) + log(w) 
has been evaluated, the result is multiplied by log(e) base 10 in double precision. 


4. For a discussion of Newton’s rule for finding roots, refer to any calculus text (for example, Calculus and 
Analytic Geometry by G. B. Thomas). 
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Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is equal to zero. 
It is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The function DLOG10 was tested against DLOG10(11x/10) - DLOG10(11/10). Groups of 
2000 arguments were chosen randomly from the interval [.3162D+00,.9000D+ 00]. 
Statistics on relative error were observed: maximum relative error was .5417D-—-27; root 
mean square relative error was .8117D-28. 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/x. 
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Example of DLOG10 Called From FORTRAN 


Source Code: 


. PROGRAM DLOG10_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The common logarithm of x is:’ 
PRINT *, DLOG10(x) 
END 
Output: 


The common logarithm of x is: 
~.30 102999566398 11952 13738895 
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DMOD 


DMOD returns the remainder of the ratio of two arguments. It accepts two double 
precision arguments and returns a double precision result. 


The call-by-reference entry points are MLP$RDMOD and DMOD, and the call-by-value 
entry point is MLP$VDMOD. 


The input domain for this function is the collection of all valid double precision pairs 
(x,y), where y is nonzero and x/y is a valid quantity. The output range is included in 
the set of valid double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
y is equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is branched to, and result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
The function computed by DMOD(x,y) is: 
x - (x/y)*y 


where parentheses denote truncation. The result of x/y is found and then added to a 
special floating-point zero that forces truncation. 
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Example of DMOD Called From FORTRAN 


Source Code: 


PROGRAM DMOD_EXAMPLE 


EXTERNAL DMOD 

DOUBLE PRECISION x, y 

y=750.0d0 

x=140.0d0 

PRINT *, “The remainder of the ratio of y and x is:’ 
PRINT *, DMOD(y,x) 

END 


Output: 


The remainder of the ratio of y and x is: 
50. 
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DNINT 


DNINT returns the nearest whole number to an argument. It accepts a double 
precision argument and returns a double precision result. 


The call- by-reference entry points are MLP$RDNINT and DNINT, and the call-by-value 
entry point is MLP$VDNINT. 


The input domain for this function is the collection of all valid double precision 
quantities. The output range is included in the set of valid integer quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is branched to, and the result is returned to the 
calling program. 


Call-By-Value Routine 


If the argument is = 0, .5 is added to it and the result is added to a special 
floating-point zero that forces truncation. If the argument is < 0, -.5 is added to it 
and the result is treated as above. 


Example of DNINT Called From FORTRAN 


Source Code: 


PROGRAM DNINT_EXAMPLE 


EXTERNAL DNINT 

DOUBLE PRECISION x 

x=99 .99d0 

PRINT *, “The DNINT of x is:’ 
PRINT *, DNINT(x) 

END 


Output: 


The DNINT of x is: 
100. 
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DPROD 


DPROD computes the product of two arguments. It accepts two real arguments and 
returns a double precision result. 


The call-by-reference entry points are MLP$RDPROD and DPROD, and the 
call-by-value entry point is MLP$VDPROD. 


The input domain for this function is the collection of all valid real pairs (x,y) such 
that x*y is a valid double precision quantity. The output range is included in the set of 
valid double precision quantities. 
Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 

x is indefinite. 

y is indefinite. 

x is infinite. 

y is infinite. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is branched to, and the result is returned to the 
call-by-reference routine. The result is checked. If the result is infinite, it is invalid, 
and a diagnostic message is displayed. If the result is valid, it is returned to the 
calling program. 


Call-By-Value Routine 


Given argument pair (x,y), the result of x*y is found. 


Example of DPROD Called From FORTRAN 


Source Code: 


PROGRAM DPROD_EXAMPLE 
EXTERNAL DPROD 
C Accepts two real arguments. Returns a double precision result. 
. x=140.0 
y=750.0 
PRINT *, “The DPROD of x and y is:’ 
PRINT *, DPROD(x,y) 
END 


Output: 


The DPROD of x and y is: 
105000. 
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DSIGN 


DSIGN transfers the sign of the second argument to the sign of the first. It accepts 
two double precision arguments and returns a double precision result. 


The call-by-reference entry points are MLP$RDSIGN and DSIGN, and the call-by-value 
entry point is MLP$VDSIGN. 


The input domain for this function is the collection of all valid double precision pairs 
(x,y). The output range is included in the set of valid double precision quantities. 
Call-By-Reference Routine 


No errors are generated by DSIGN. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The sign bit of the second argument is isolated by a mask with all other bits zero. The 
sign bits of the upper and lower words of the first argument are cleared by a boolean 
AND mask and replaced by the sign of the second argument by a boolean ne usive OR 
with the complement of the mask. 


Given arguments (x,y): 


result = [x] if y is nonnegative 
result = -|xl if y is negative 
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Example of DSIGN Called From FORTRAN 


Source Code: 


Output: 


PROGRAM DSIGN_EXAMPLE 


EXTERNAL DSIGN 
DOUBLE PRECISION x, y 
x=-140.0d0 

y=750.0d0 

PRINT *, “The DSIGN of x,y is:’ 
PRINT *, DSIGN(x,y) 

END 


The DSIGN of x,y is: 


140. 
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DSIN 


DSIN computes the sine function. It accepts a double precision argument and returns a 
double precision result. 


The call-by-reference entry points are MLP$RDSIN and DSIN, the call-by-value entry 
point is MLP$VDSIN, and the vector entry point is MLP$DSINV. 


The input domain for this function is the collection of all valid double precision 
quantities whose absolute value is less than 2**47. The output range is included in the 
set of valid double precision quantities in the interval [-1.0,1.0]. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

Its absolute value is greater than or equal to 2**47. 
If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 


the call-by-value routine is called, and the result is returned to the calling program. 


Call-By-Value Routine 


Upon entry, the argument x is made positive and is multiplied by 2/pi in double 
precision, and the nearest integer n to x*2/pi is computed. At this stage, x*2/pi is 
checked to see that it does not exceed 2**47. If it does, a diagnostic message is 
returned. Otherwise, y = x — n*pi/2 is computed in double precision as the reduced 
argument, and y is in the interval [-pi/4,pi/4]. The value of mod(n,4), the entry point 
called, and the original sign of x determine whether a sine polynomial approximation 
p(x) or a cosine polynomial approximation q(x) is to be used. A flag is set to indicate 
the sign of the final result. 


For x in the interval [-pi/4,pi/4], the sine polynomial approximation is: 


p(x) = a(1)x + a(3)x**3 + a(5)x**5 + a(7)x**7 + a(9)x**9 + a(11)x**11 + 
a(13)x**13** + a(15)x**15 + a(17)x**17 + a(19)x**19 + a(21)x**21 


and the cosine polynomial approximation is: 


a(x) = b(O) + b(2)x**2 + b(4)x**4 + b(6)x**6 + bD(8)x**8 + b(10)x**10 + 
b(12)x**12 + b(14)x**14 + b(16)x**16 + b(18)x**18 + b(20)x**20 
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The coefficients are: 


a(1) = 
a(3) = 
a(5) = 
a(7) = 
a(9) = 
a(11) = 
a(13) = 
a(15) = 
a(17) = 
a(19) = 
a(21) = 
b(0) = 
b(2) = 
b(4) = 
b(6) = 
b(8) = 
b(10) = 
b(12) = 
b(14) = 
b(16) = 
b(18) = 
b(20) = 


.999 
. 166 
.833 
. 198 
.275 
. 250 
. 160 
. 764 
.281 
.822 
. 194 
.999 
-499 
-416 
. 138 
. 248 
275 
.208 
.114 
.477 
. 156 
.408 


999 
666 
333 
412 
573 
521 
590 
716 
145 
042 
362 
999 
999 
666 
888 
015 
573 
767 
707 
947 
187 
023 


999 
666 
333 
698 
192 
083 
438 
373 
706 
461 
013 
999 
999 
666 
888 
873 
192 
569 
455 
696 
668 
947 


999 
666 
333 
412 
239 
854 
368 
079 
930 
317 
130 
999 
999 
666 
888 
015 
239 
878 
958 
822 
345 
777 


999 
666 
333 
698 
858 
417 
179 
886 


999 
666 
333 
412 
906 
101 
417 
084 


999 
666 
333 
698 
394 
138 
271 
755 


018*10**-14 
923*10**-17 
224* 10**-19 


999 
999 
666 
888 
873 
858 
619 
584 
393 


999 
999 
666 
888 
015 
775 
214 
315 
115 


999 
999 
666 
888 
699 
558 
898 
495 
933 


316* 10**-15 
860* 10**-18 


999 
666 
332 
291 
406 
076 
194 
348 


999 
999 
666 
755 
922 
669 


747 


950 
106 


999 
666 
709 
344 
844 
473 
064 
748 


999 
999 
139 
436 
737 
957 
461 
765 
267 


DSIN 


99 

52 

577 10**=2 
78* 10**-3 
01*10**-5 
5*10**-7 
61*10**-9 
S1*10**=12 


99 
19 
02 
28* 10**-2 
30* 10**-4 
11*10**-6 
35* 10**-8 
75* 10**-10 
21*10**-13 


These polynomials are evaluated from right to left in double precision. The sign flag is 
used to give the result the correct sign before returning to the calling program. 


Vector Routine 


The argument is checked upon entry. It is invalid if: 


It is indefinite. 


It is infinite. 


Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The maximum absolute value of the error of approximation of p(x) to sin(x) over 
(-pi/4,pi/4) is .2570E-28, and of q(x) to cos(x) is .3786E—-28. 


The function DSIN was tested against the 3*DSIN(x/3) - 4*DSIN(x/3)**3. Groups of 
2,000 arguments were chosen randomly from given intervals. Statistics on relative error 
were observed. Table 8-14 shows a summary of these statistics. 


Table 8-14. Relative Error of DSIN 


Root Mean 
Interval From Interval To Maximum Square 
0.0000D+00 .1571D+01 .5153D-28 .1254D-28 
.1885D + 02 .2042D+02 .2764D-23 .6188D-25 


Effect of Argument Error 
If a small error e occurs in the argument x, the resulting error in sin is given 


approximately by e*cos(x). If the error e becomes significant, the addition formulas for 
sin and cos should be used to compute the error in the result. 
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Example of DSIN Called From FORTRAN 


Source Code: 


PROGRAM DSIN_EXAMPLE 


Cc 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DSIN of x is:’ 
PRINT *, DSIN(x) 
END 

Output: 


The DSIN of x is: 
-479425538604203000273287935 
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DSINH computes the hyperbolic sine function. It accepts a double precision argument 
and returns a double precision result. 


The call-by-reference entry points are MLP$RDSINH and DSINH, the call-by-value 
entry point is MLP$VDSINH, and the vector entry point is MLP$SINHV. 


The input domain for this function is the collection of all valid double precision 
quantities whose absolute value is less than 4095*log(2). The output range is included 
in the set of valid double precision quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 4095*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result is returned to the calling program. 


Call-By-Value Routine 


Most of the computation is performed in routine DEULER, and the constants used are 
listed there. The argument reduction performed in DEULER is: 


xX = argument 
y = reduced argument 
y = x - n*log(2) 


where n is an integer, and y is in the interval [-1/2*log(2),1/2*log(2)]. 
The formula used for computation is: 


sinh(y + n*log(2)) = (cosh(y) + sinh(y))*2**(n-1.0) - (cosh(y) - 
sinh(y) )*2**(-n-1.0) 


where 
cosh(y) = DC, and sinh(y) = DS as computed in routine DEULER. 


On input, the argument is in register pair (X2,X3), and on output, the result is in 
register pair (XE,XF). 


See the description of routine DEULER in chapter 9, Auxiliary Routines, for detailed 
information. 
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Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 4095*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-15 shows a summary of these statistics. 


Table 8-15. Relative Error of DSINH 


Root Mean 
Test Interval From Interval To Maximum Square 
DSINH(x) against 0.0000D+00 .5000D+00 .1184D-27 .3084D-28 
Taylor series expansion 
of DSINH(x) 
DDINH(x) against .3000D+01 .2838D+04 .1178D-27 .4582D-28 


c*(DSINH(x + 1) + 
DSINH(x — 1)) 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in sinh(x) is approximately 
cosh(x)*e. 


Example of DSINH Called From FORTRAN 


Source Code: 


PROGRAM DSINH_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DSINH of x is:’ 
PRINT *, DSINH(x) 
END 
Output: 


The DSINH of x is: 
-52 10953054937 4736 1622425626 
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DSQRT 


DSQRT computes the square root. It accepts a double precision argument and returns a 
double precision result. 


The call-by-reference entry points are MLP$RDSQRT and DSQRT, the call-by-value 
entry point is MLP$VDSQRT, and the vector entry point is MLP$DSQRTV. 


The input domain for this function is the collection of all valid, nonnegative double 
precision quantities. The output range is included in the set of valid double precision 
quantities. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is negative. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


An initial approximation to sqrt(y) is obtained by evaluating, inline, the sqrt of y(u) in 
single precision. . 


One Heron’s iteration is performed in double precision using y and the initial 
approximation of sqrt(y), giving the double precision result. 


Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 
The algorithm error is at most 2.05E-31, and is always positive. 


The function DSQRT was tested against DSQRT(x*x) - x. Groups of 2,000 arguments 
were chosen randomly from given intervals. Statistics on relative error were observed. 
Table 8-16 shows a summary of these statistics. 


Table 8-16. Relative Error of DSQRT 


Root Mean 
Interval From Interval To Maximum Square 
.1000D+01 .1414D+01 .0000D+00 .0000D + 00 
.7071D+ 00 .1000D+01 .1785D-28 .9981D-29 


Effect of Argument Error 


For a small error e in the argument y, the amplification of absolute error is 
e/2*sqrt(y)). 


Example of DSQRT Called From FORTRAN 


Source Code: 


PROGRAM DSQRT_EXAMPLE 


C 
DOUBLE PRECISION x 
x=49 .0d0 
PRINT *, “The DSQRT of x is:’ 
PRINT *, DSQRT(x) 
END 
Output: 


The DSQRT of x is: 
7. 
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DTAN is a function that computes the tangent function. It accepts a double precision 
argument and returns a double precision result. 


The call-by-reference entry points are MLP$RDTAN and DTAN, the call-by-value entry 
point is MLP$VDTAN, and the vector entry point is MLP$DTANV. 


The input domain for this function is the collection of all valid double precision 
quantities whose absolute value is less than 2**47. The output range is included in the 
set of valid double precision quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 
The argument reduction is performed in two steps: 


1. A pi/2 reduction is performed first. If the argument is outside the interval 
[-pi/4,pi/4], a signed integer multiple n of pi/2 is computed such that, after adding 
it to the argument, the result z falls in the interval [—pi/4,pi/4]. 


2. A 1/8 reduction is performed next. A signed integer m, which is a multiple of 1/8, 
is subtracted from z such that the result is in the interval [-1/16,1/16]. A small 
number e(m) is also subtracted from z. The value of e(m) is constant such that the 
tangent of m/8 + e(m) can be represented to double precision accuracy in a single 
precision word. The lower word is zero. Therefore, the original argument y is 
reduced to x as follows: 


x = y - (n*pi/2) - (m/8 + e(m)) 


The following quantities are computed from the reduced argument x and from the 
range reduction values. The functions U and L represent “upper of" and "lower of" 
functions. 


tan(m/8 + e(m)) 
L(U(x)**2)/2U(x) + L(x) 
L(U(x)**2) + 2L(x)U(x) 
U(U(x) **2) 


oT My DF ot 
iow on 
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Since: 


tan(x) = tan(sart(x**2)) 

tan(sart (U(U(x)**2 + L(U(x)**2) + 2L(x)U(x))) 
tan(sqrt(b + a)) 

tan(sqrt(b) + a/2b) 

= tan(sart(b) + r) 


Then s = sqrt(b) = U(x) -— L(U(x)**2)/2U(x) 
The value of the original argument y is: 
 tan(y) = tan(x + n*pi/2 + m/8 + e(m)) 


The effect of the n*pi/2 term on the final result is: 


tan(y) = tan(x + m/8 + e(m)), if n is even 
tan(y) = 1/tan(x + m/8 + e(m)), if n is odd 


Applying the tangent addition formula gives: 
tan(x + m/8 + e(m)) = tan(s + r + (m/8 + e(m)) 


tan(s) + tan(r) + t - tan(s)*tan(r)*t 


1.0 - tan(s)*tan(r) - tan(r)*t - t*tan(s) 


tan(s) +r+t - tan(s)*r*t 


1.0 - tan(s)*r - r*t - t*tan(s) 
Tan(s) is computed by using the general polynomial form: 
xX + x**3/3 + x**5*2/315 . 
After Chebyshev is applied to the coefficients, the form is: 


tan(s) = s + s*(c(1)s**2 + c(2)s**4 + c(3)s**6 + c(4)s**8 + 
(a/(b - s**2))s**10) 


where a = .0218 ... and b = 2.467 ... 


The quotient is inverted if n is odd. 
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Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The algorithm error has a negligible effect on the total error. The worst relative error 
of the algorithm is 1.032E-29. There is a negligible error introduced by the pi/2 range 
reduction except for points close to nonzero multiples of pi/2. Near pi/2, the pi/2 
reduction relative error is bounded by 2**(n-155) where n is the number of bits of 
precision to which the argument represents pi/2. At larger multiples of pi/2, similar 
problems occur. 


The function DTAN was tested against 2*DTAN(x/2)/((1 — DTAN(x/2)**2). Groups of 
2,000 arguments were chosen randomly from given intervals. Statistics on relative error 
were observed. Table 8-17 shows a summary of these statistics. 


Table 8-17. Relative Error of DTAN 


Root Mean 
Interval From Interval To Maximum Square. 
.0000D +00 .7854D+00 .1946D-27 .4491D-28 
.1885D + 02 .1963D+02 .1729D-27 .4480D-28 
.2749D +01 .3534D+01 .2008D-27 .5363D-28 
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Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is e*sec(x)**2.: 
Example of DTAN Called From FORTRAN 


Source Code: 


PROGRAM DTAN_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DTAN of x is:’ 
PRINT *, DTAN(x) 
END 
Output: 


The DTAN of x is: 
-5463024898437905 13255 179466 
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DTANH 


DTANH computes the hyperbolic tangent function. It accepts a double precision 
argument and returns a double precision result. 


The call-by-reference entry points are MLP$RDTANH and DTANH, the call-by-value 
entry point is MLP$VDTANH, and the vector entry point is MLP$DTANHV. 


The input domain for this function is the collection of all valid double precision 
quantities. The output range is included in the set of valid quantities in the interval 
[-1.0,1.0]. 

Call-By-Reference Routine 


The argument is checked upon entry. It is invalid if it is indefinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


Most of the computation is performed in routine DEULER, and the constants used are 
listed there. The argument reduction performed is: 


1. For argument in [-47*log(2),47*log(2)] but not in [-1/2*log(2),1/2*log(2)): 


x = argument 
y = reduced argument 
y = 2x - n*log(2) 


where n is an integer, and y is in [-1/2*log(2),1/2*log(2)] 


tanh(x) = u/v where 


u 1.0 - 2**-n - 2**-n*(DC - DS) 
v= 1.0 - 2**-n + 2**-n*(DC - DS) 


2. For argument in [-1/2*log(2),1/2*log(2)): 


xX = argument 
y = reduced argument 
y=xX 

tanh(x) = DS(2*+DC) 


3. For argument outside [-47*log(2),47*log(2)]: 
X = argument 


y = reduced argument 
tanh(x) = 1.0 - 2((1.0 + DC - DS)*2**-n - ((1.0 + DC - DS)*2**-n)**2) 


In steps 1, 2, and 3, DC = cosh(y) - 1.0 and DS = sinh(y), where DC + DS are 
computed in DEULER. 


On input, the argument is in register pair (X2-X3), and on output, the result is in 
register pair (XE-XF). 
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Vector Routine 
The argument is checked upon entry. It is invalid if it is indefinite. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The function DTANH was tested against (DTANH(x - 1/8) + DTANH(1/8))(1 + 
DTANH(x —- 1/8)*DTANH(1/8)). Groups of 2,000 arguments were chosen randomly from 
given intervals. Statistics on relative error were observed. Table 8-18 shows a summary 
of these statistics. 


Table 8-18. Relative Error of DTANH 


Root Mean 
Interval From Interval To Maximum Square 
.1250D +00 .5493D+00 .9403D-28 .2612D-—28 
.6743D + 00 .84381D+02 .3282D-27 .2348D-28 


Algorithm Error 
The algorithm error is insignificant. It is predominated by the error in the sinh 


expression in DEULER, but by various folding actions, the error is reduced even 
further. | 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given by 
e*sech(x)**2. 


Example of DTANH Called From FORTRAN 


Source Code: 


PROGRAM DTANH_EXAMPLE 


C 
DOUBLE PRECISION x 
x=0.5d0 
PRINT *, “The DTANH of x is:’ 
PRINT *, DTANH(x) 
END 
Output: 


The DTANH of x is: 
.462117 1572600097585023 18484 
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DTOD performs exponentiation for program statements that raise double precision 
quantities to double precision exponents. It accepts two double precision arguments and 
returns a double precision result. DTOD also accepts compiler-generated calls (for 
example, the FORTRAN and Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RDTOD and DTOD, and the call-by-value 
entry point is MLP$VDTOD. 


The DTOD vector math function is divided into three routines having three separate 
entry points defined as follows: 


DTOD(scalar,vector) = MLP$DTODV 
DTOD(vector,scalar) = MLP$DVTOD 
DTOD(vector, vector) = MLP$DVTODV 


The input domain for this function is the collection of all valid double precision pairs 
(x,y), where x is positive and x**y is a valid quantity. If x is equal to zero, then y 
must be greater than zero. The output range is included in the set of valid, positive 
double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
x is negative. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 
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Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 0. 
Upon entry, the routine calls DLOG to compute log(x), and DEXP to compute 
exp(y*log(x)). 
‘Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
x is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The function DTOD was tested. Groups of 2,000 arguments were chosen randomly from 
given intervals. Statistics on relative error were observed. Table 8-19 shows a summary 


of these statistics. 


Table 8-19. Relative Error DTOD 


Test Interval From 

x interval 

x**y against x**2**(y/2) .1000D-01 

y interval 

-.6167D+03 

HPFZET1S .1000D+01 
against 

KetZ*x .5000D+ 00 

x**1.0 against x .5000D +00 


Effect of Argument Error 


Interval To 


.1000D + 02 


.6167D + 03 
.80534+ 411 
.1000D+01 


.1000D+01 


Maximum 


.5172D-25 


.1133D-24 


.1143D-27 


.7133D-28 


Root Mean 
Square 


.9207D-26 


.4805D-25 


.3978D-28 
.3195D-28 


If a small error e(b) occurs in the base b and a small error e(p) occurs in the exponent 
p, the error in the result r is given approximately by: 


r*(log(b)*e(p) + p*e(b)/b) 
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Example of DTOD Called From FORTRAN 


Source Code: 


PROGRAM DTOD_EXAMPLE 


DOUBLE PRECISION x, y, DTOD 
x=20.0d0 

y=140.0d0 

PRINT *, “The DTOD of x and y is:’ 
PRINT *, DTOD(x,y) 

END 


Output: 


The DTOD of x and y is: 
1.39379657 4908 16394634598238E+182 
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DTOI performs exponentiation for program statements that raise double precision 
quantities to double precision exponents. It accepts two double precision arguments and 
returns a double precision result. DTOI also accepts compiler-generated calls (for 
example, the FORTRAN and Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RDTOI and DTOI, and the call-by-value 
entry point is MLP$VDTOI. 


The DTOI vector math function is divided into three routines having three separate 
entry points defined as follows: 


DTOI(scalar,vector) = MLP$DTOIV 
DTOI(vector,scalar) = MLP$DVTOI 
DTOI(vector,vector) = MLP$DVTOIV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a double precision quantity and y is an integer quantity. If x is equal to zero, then y 
must be greater than zero. The output range is included in the set of valid double 
precision quantities. 


Call-By-Reference Routine 

The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
x infinite. 
x is equal to zero and y is less than or equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
An x represents the base, and a y represents the exponent. If y is nonnegative and has 
the binary representation 000...0i(n)i(n-1)...i(1)i(0), where each i(j)(0 = j = n) is 0 or 
1, then: 

y = i(n)*2**n + i(n-1)*2**(n-1) + ... + i1(1)*2**1 + 1(0)*2**0 
and n = (log(2)y) = greatest integer not exceeding log(2)y. Then: 


x**y = prod[x**2**j : 0 < j <n and i(j) = 1]. 
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The numbers x = x**0, x**2**0, x*¥*2, x**4, ..., x**2n are generated by successive 
squarings, and the coefficients i(n), ..., i(0) are obtained as the sign bits of successive 
circular left shifts of y within the computer. A running product is formed during the 
computation so that smaller powers of x and earlier coefficients i(j) can be discarded. 
Thus, the computation becomes an iteration of the algorithm: 


x**y = 1, if y = 0 and x not= 0. 
(x**2)**(y/2), if y > 0 and y is even. 
x*(x**2)**((y - 1)/2), if y > 0 and y is odd. 


HF 


Upon entry, if the exponent y is negative, the following steps are performed with R(k) 
representing the running product after k iterations: 


1. y is replaced by —y. 


2. y is shifted right (end-off) by 1. 


This effectively divides y by 2 and the final multiplications are completed after the 
running product, R(n-1) is replaced by 1/R(n-1) in the case of exponent overflow for 
very large negative exponents. 


3. The algorithm continues as if the exponent was positive with the above formula for 
(n-1) iterations. 


4. Either of the following two methods produces the final result R(n): 


a. If the final multiplication (depending on i/n and the last bit of the power) 
R(n-1) ** 2 * (x ** i(j)) gives exponent overflow, then the running product after 
(n-1) iterations is inverted and the result is: 


R(n) = (1/(R(n-1)) * (1/(x ** i(53))), j =n 
b. If there is no exponent overflow in the final multiplication, the result is: 
R(n) = (1/(R(n-1) ** 2 * (x ** i(j))) 


In the routine, double precision quantities a = a(u)*a(l) and b = b(u)*b(1) are 
multiplied according to: 


a*b = (a*b)(u)*(a*b)(1) 


where: 

(a*b)(u) = (((a(u)*b(1)) + (a(1)*b(u))) + (a(u)*(1)b(u))) + (a(u)*b(u)) 
and 

(a*b)(1) = (((a(u)*b(1)) + (a(1)*b(u))) + (a(u)*(1)b(u))) + (1) (alu) *b(u)) 
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Vector Routine 

The argument pair (x,y) is checked upon entry. It is invalid if: | 
x is indefinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 


) 
See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Effect of Argument Error 


If a small error e occurs in the base b, the error in the result will be given 
approximately by n*b**(n-1)*e, where n is the exponent given to the routine. 


8-124 Math Library 60486513 H 


DTOI 


Example of DTOI Called From FORTRAN 


Source Code: 


PROGRAM DTOI_EXAMPLE 


INTEGER i 
DOUBLE PRECISION d, dtoi 

i=2 

d=10.0d0 

PRINT *, “The DTOI of d and i is:’ 
PRINT *, DTOI(d,i) 

END 


Output: 


The DTOI of i and d is: 
100. 
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DTOX performs exponentiation for program statements that raise double precision 
quantities to double precision exponents. It accepts two double precision arguments and 
returns a double precision result. DTOX also accepts compiler-generated calls (for 
example, the FORTRAN and Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RDTOX and DTOX, and the call-by-value 
entry point is MLP$VDTOX. 


The DTOX vector math function is divided into three routines having three separate 
entry points defined as follows: 


DTOX(scalar,vector) = MLP$DTOXV 
DTOX(vector,scalar) = MLP$DVTOX 
DTOX(vector,vector) = MLP$DVTOXV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a nonnegative double precision quantity and y is a real quantity. If x is equal to zero, 
then y must be greater than zero. The output range is included in the set of valid, 
positive double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 

x is indefinite. 

y is indefinite. 

x is infinite. 

y is infinite. 

x is equal to zero and y is less than or equal to zero. 

x is negative. 
If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 


it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 0 


Upon entry, the routine calls DLOG to compute log(x), and DEXP to compute 
exp(y*log(x)). 
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Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
x is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


See the description of function DTOD. 


Effect of Argument Error 


If a small error e(b) occurs in the base b and a small error e(p) occurs in the exponent 
p, the error in the result r is given approximately by: 


r*(e(p)*log(b) + p*e(b)/b) 
Example of DTOX Called From FORTRAN 


Source Code: 


PROGRAM DTOX_EXAMPLE 


REAL x 
DOUBLE PRECISION d, dtox 

x=2.0 

d=10.0d0 . 

PRINT *, “The DTOX of d and x is:’ 
PRINT *, DTOX(d,x) 

END 


Output: 


The DTOX of d and x is: 
100. 
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DTOZ performs exponentiation for, program statements that raise double precision 
quantities to double precision exponents. It accepts two double precision arguments and 
returns a double precision result. DTOZ also accepts compiler-generated calls (for 
example, the FORTRAN and Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RDTOZ and DTOZ, and the call-by-value 
entry point is MLP$VDTOZ. 


The DTOZ vector math function is divided into three routines having three separate 
entry points defined as follows: 


DTOZ(scalar,vector) = MLP$DTOZV 
DTOZ(vector,scalar) = MLP$DVTOZ 
DTOZ(vector,vector) = MLP$DVTOZV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a double precision quantity and y is a complex quantity. If x is equal to zero, then the 
real part of y must be greater than zero, and the imaginary part must be equal to 
zero. The output range is included in the set of valid double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 


x is equal to zero, and the real part of y is less than or’ equal to zero, or the 
imaginary part of y is not equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is I 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 


it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
If the base is real and the exponent is complex, then: 
base**exponent = x + i*y 


Upon entry, the double precision base, x, is converted to complex, and the routine calls 
ZTOZ to compute the result. 
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Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
y is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 


x is equal to zero, and the real part of y is less than or equal to zero, or the 
imaginary part of y is not equal to zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 
A group of 10,000 arguments was chosen randomly from the interval 


([-1.0,1.0] [-1.0,1.0]) and ({-1.0,1.0],[-1.0,1.0]). The maximum relative error of these 
arguments was found to be 1.7431E-11. 


Effect of Argument Error 


If a small error e(b) occurs in the base b and a small error e(z) occurs in the exponent 
z, the error in the result w is given approximately by: 


w*(e(z)*log(b) + z*e(b)/b) 


Example of DTOZ Called From FORTRAN 


Source Code: 


PROGRAM DTOZ_EXAMPLE 


C 

COMPLEX zeta, dtoz 
DOUBLE PRECISION d 
zeta = (5.0, -1) 
d=10.0d0 
PRINT *, “The DTOZ of d and zeta is:’ 
PRINT *, DTOZ(d,zeta) 
END 

Output: 


The DTOZ of d and zeta is: 
(-66820.15101903, -74398.03369575) 
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ERF 


ERF computes the error function. It accepts a real argument and returns a real result. 


The call-by-reference entry points are MLP$RERF and ERF, the call-by-value entry 
point is MLP$VERF, and the vector entry point is MLP$ERFV. 


The input domain for this function is the collection of all valid real quantities. The 
output range is included in the set of real quantities in the interval [-1.0,1.0]. 
Call-By-Reference Routine 


The argument is checked upon entry. It is invalid if it is indefinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


The routine calculates the smaller of erf(abs(x)) and erfc(abs(x)). The final value, which 
is the sum of a signed function and a constant, is computed by using the identities: 


erf(-x) = -erf(x) 
erf(x) = 1.0 - erfc(x) 


The forms used in ERF (y = ABS(x)) are given in table 8-20. 


Table 8-20. Forms Used in ERF 


Range ERF ERFC 
[~INF,-5.625] -1.0 +2.0 
(-5.625,-.477)  -1.0+ p2(y) +2.0—p2(y) 
[-.477,0) -pl(y) +1.0+pl(y) 
[0,+.477] +pl(y) +1.0-pl(y) 
[.477,5.625) +1.0-p2(y) p2(y) 
[5.625,8.0) +1.0 p2(y) 
[8.0,53.0] +1.0 p3(y) 

(53.0, + INF) +1.0 underflow 
+INF +1.0 0.0 


The constants .477 and 53.0 are inverse erf(.5) and inverse erfc(2**-975), which are 
approximately .47693627620447 and 53.0374219959898. 


The function pl is a (5th order odd)/(8th order even) rational form. The functions p2 
and p3 are exp(-x**2)*(rational form), where p2 is (7th order)/(8th order) and p3 is 
(4th order)/(5th order). Since exp(—x**2) is ill-conditioned for large x, exp(-x**2) is 
calculated by exp(u + e) = exp(u) + e*exp(u), where u = ~x**2 upper and e = 
—x**2 lower. 


5. The coefficients for p2 and p3 are from Hart, Cheney, Lawson, et al., Computer Approximations, New 
York, 1968, John Wiley and Sons. 
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Vector Routine 
The argument is checked upon entry. It is invalid if it is indefinite. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The function ERF was tested against 1 - e**(—x**2)*p(x)/q(x)’. A group of 10,000 
arguments was chosen randomly from the interval (0.0,8.0). The maximum relative 
error of these arguments was found to be .2050E-13. 


Effect of Argument Error 


For small errors in the argument x, the amplification of absolute error is 
(2/sqrt(pi))*exp(—x**2) and that of relative error is (2/sqrt(pi))*x*exp(—x**2)/f(x) where f 
is erf or erfc. The relative error is attenuated for ERF everywhere and for ERFC when 
x < .53. For x > .53, the relative error for ERFC is amplified by approximately 2x. 


Example of ERF Called From FORTRAN 


Source Code: 


PROGRAM ERF_EXAMPLE 


C 
REAL x 
x= 100000 .0 
PRINT *, “The error function of x is:’ 
PRINT *, ERF(x) 
END 
Output: 


The error function of x is: 
1. 
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ERFC computes the complementary error function. It accepts a real argument and 
returns a real result. , 


The call-by-reference entry points are MLP$RERFC and ERFC, the call-by-value entry 
point is MLP$VERFC, and the vector entry point is MLP$ERFCV. 


The input domain for this function is the collection of all valid real quantities less 
than 53.037, but not equal to infinity. The output range is included in the set of valid, 
nonnegative real quantities less than or equal to 2.0. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is greater than 53.037, but not equal to infinity. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


The routine calculates the smaller of erf(abs(x)) and erfc(abs(x)). The final value, which 
is the sum of a signed function and a constant, is computed by using the identities: 


erf(-x) = -erf(x) 
erf (x) 1.0 - erfc(x) 


The forms used are given in table 8-20. 


Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is greater than 53.037, but not equal to infinity. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The function ERFC was tested against e**(—x**2)*p(x)/q(x)’. A group of 10,000 
arguments was chosen randomly from the interval (0.0,8.0). The maximum relative 
error of these arguments was found to be .9531E-11. 


Effect of Argument Error 


For small errors in the argument x, the amplification of absolute error is 
(2/sqrt(pi))*exp(-x**2) and that of relative error is (2/sqrt(pi))*x*exp(—x**2)/f(x) where f 
is erf or erfc. The relative error is attenuated for ERF everywhere and for ERFC when 
x < .53. For x > .53, the relative error for ERFC is amplified by approximately 2x. 


Example of ERFC Called From FORTRAN 


Source Code: 


PROGRAM ERFC_EXAMPLE 


C 
REAL x 
x=53 .036 
PRINT *, “The complementary error function of x is:’ 
PRINT *, ERFC(x) 
END 
Output: 


The complementary error function of x is: 
2.7273877275 15E-1224 
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EXP computes the exponential function. It accepts a real argument and returns a real 
result. 


The call-by-reference entry points are MLP$REXP and EXP, the call-by-value entry 
point is MLP$VEXP, and the vector entry point is MLP$EXPV. 


The input domain for this function is the collection of all valid real quantities whose 
value is greater than or equal to —4097*log(2) and less than or equal to 4095*log(2). 
The output range is included in the set of valid positive real quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 

It is greater than 4095*log(2). 

It is less than —4097*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
call-by-reference routine. The result is checked. If the result is infinite, it is invalid, 
and a diagnostic message is displayed. If the result is valid, it is returned to the 
calling program. 
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Call-By-Value Routine 


If x is valid, EXP(x) is calculated by reducing it to the simpler task of approximating 
e**g*2**(NL/32). This reduction is derived as follows: 


exp(x) = e**(g + (32*NH + NL)*(1n(2)/32)) 
e**(g + NH*1n(2) + (NL/32)*1n(2)) 
e* *g*2**NH*2**(NL/32) 
(e**g*2**(NL/32)) *2**NH 


where 


- nis the nearest integer to 32*x/In(2). 

- gis a real number such that x = g + n*(1In(2)/32). Thus, 
abs(g) is less than or equal to In(2)/64. 

- WH is floor(n/32). 

= NL is greater than or equal to 0, Jless'than or equal to 31, 
and is the integer such that n = 32*NH + NL. 


The reduction: 
e**g*2**(NL/32) 

is approximated to 48 bits of precision using the following minimax approximation: 
Z = Q(NL, g) + Qbias(NL) 


where for each of the 32 values of NL, Qbias(NL) is a number that is represented 
exactly in binary floating-point and which is slightly less than 2**(-1/64)*2**(NL/32), 
which is the minimum value of e**g*2**(NL/32). 


Q(NL, g) denotes the 32 quintic polynomials in g which approximate e**g*2**(NL/32) — 
Qbias(NL) with the lowest maximum relative error for abs(g) = 1n(2)/64. Z is evaluated 
with almost no error since the low bits of Q(NL, g), which may be inaccurate due to 
truncation errors, are insignificant with respect to Qbias(NL). Thus, Z*2**NH, which is 
evaluated simply by adding NH to the exponent of Z, is an accurate approximation to 
EXP(x). 
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Vector Routine 


The argument is checked upon entry. It is invalid if: 


It is indefinite. 
It is infinite. 
It is greater than 4095*log(2). 


It is less than —4097*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-21 shows a summary of these statistics. 


Table 8-21. Relative Error EXP 


Test Interval From 
EXP(x - 2.8125) -.3466E +01 
against 


EXP(x)/EXP(2.8125) 


EXP(x - .0625) against ~-.2841E +00 
EXP(x)/EXP(.0625) 

EXP(x - 2.8125) .6931E+01 
against 

EXP(x)/EXP(2.8125) 
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Interval To 


-.2805E + 04 


.3466E + 00 


.2838E + 04 


Maximum 


.1335E-14 


155 7TE-14 | 


.17384E-14 


Root Mean 
Square 


.3766E-14 


.3945E-14 


.3850E-14 
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Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result y is given be y*e. 


Example of. EXP Called From FORTRAN 


Source Code: 


PROGRAM EXP_EXAMPLE 


C 
REAL x 
x=1000.0 
PRINT *, “The EXP of x is:’ 
PRINT *, EXP(x) 
END 
Output: 


The EXP of x is: 
1.970071114017E+434 
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EXTB extracts bits from the first argument, x, as specified by the second and third 
arguments, il and i2; that is, EXTB(x, il, i2) extracts bits from x starting with 
position il with length of i2. It accepts any type except character for argument x and 
accepts integer for arguments il and i2. The result is boolean. 


If x is of type double precision or complex, only the first word is used. The result is 
returned with a zero-filled second word. The following example FORTRAN program 
uses function EXTB with double precision arguments to illustrate the zero-filled second 
word. 


Source Code: 


PROGRAM EXTB_EXAMPLE 


EXTERNAL EXTB 
DOUBLE PRECISION d1,d2 

BOOLEAN x(2),y(2) 

EQUIVALENCE (x(1),d1),(y(1),d2) 
x(1)=Z" 1234567 890ABCDEF" 
x(2)=Z" FEDCBA098765432 1" 
y(1)=Z2"1111919111111111" 

y (2)=Z"2222222222222222" 
d2=EXTB(d1,0,32) 

PRINT *,x(1),x(2) 

PRINT *,y(1),y(2) 

END 


Output: 


Z"1234567890ABCDEF" Z"FEDCBA0987654321" 
Z2"12345678" Z"0" 


Argument x must be byte aligned and be at least 64 bits in length. The argument used 
is the leftmost 64 bits of x. Argument il indicates the first bit to be extracted 
numbering from bit 0 on the left. Argument i2 indicates the number of bits to be 
extracted. The extracted bits occupy the rightmost bits of the result, with 0 bits as fill 
on the left. 


The call-by-reference entry points are MLP$REXTB and EXTB, and the call-by-value 
entry point is MLP$VEXTB. 


The input domain for this function is such that il is greater than or equal to 0 and 
less than 64; i2 is greater than or equal to 0; and il + i2 is less than or equal to 64. 
If i2 = 0, the result is 0 (all 0 bits). The data type of argument x is not significant to 
the processing of this function. The output range is included in the set of valid boolean 
quantities. 
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Call-By-Reference Routine 
The arguments il and i2 are checked upon entry. They are invalid if: 
il is less than zero. 
i2 is less than zero. 
il is greater than or equal to 64. 
il + i2 is greater than 64. 
If the arguments are invalid, a diagnostic message is displayed. If the arguments are 


valid, the call-by-value routine is branched to, and the result of the function is 
returned to the calling program. 


Call-By-Value Routine 


The extracted bits from the first argument, x, as specified by the second and third 
arguments, il and i2, are returned. The leftmost 64 bits of x are used. 


Example of EXTB Called From FORTRAN 


Source Code: 


PROGRAM EXTB_EXAMPLE 


Cc 

EXTERNAL EXTB 
REAL x 
INTEGER i1, i2 
X=Z" 432 1FEDCBA987654" 
i1=1 
i12=48 
PRINT *, “The EXTB of x is:’ 
PRINT *, EXTB(x,i11,12) 
END 

Output: 


The EXTB of xX is: 
Z" 432 1FEDCBA98" 
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TABS 


IABS computes the absolute value of an argument. It accepts an integer argument and 
returns an integer result. 


The call-by-reference entry points are MLP$RIABS and JABS, and the call-by-value 
entry point is MLP$VIABS. 


The input domain for this function is the collection of all valid integer quantities. The 
output range is included in the set of valid, nonnegative integer quantities. 


Call-By-Reference Routine 


No errors are generated by IABS. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The sign bit of the argument is extended throughout a word to form a mask. The 
argument is subtracted from the exclusive OR of the mask and the argument to form 
the result. ; 


Example of IABS Called From FORTRAN 


Source Code: 


PROGRAM IABS_EXAMPLE 


Cc 

EXTERNAL IABS 
INTEGER i 
i=-40.0 
PRINT *, “The absolute value of i is:’ 
PRINT *, IABS(i) 
END 

Output: 


The absolute value of i is: 
40 
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IDIM 


IDIM computes the positive difference between two arguments. It accepts two integer 
arguments and returns an integer result. 


The call-by-reference entry points are MLP$RIDIM and IDIM, and the call-by-value 
entry point is MLP$VIDIM. 


The input domain for this function is the collection of all valid integer pairs (x,y) such 
that x - y is less than 2**63. The output range is included in the set of valid, 
nonnegative integer quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
x - y is greater than or equal to 2**63. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


Upon entry, the difference between the two arguments is formed, and the sign bit is 
extended across another word to form a mask. The boolean product of the mask’s 
complement and the difference is formed. 


Given arguments (x,y): 


result = x -y if x>y 
result = 0 if x <y. 


Example of IDIM Called From FORTRAN 


Source Code: 


PROGRAM IDIM_EXAMPLE 


C 

EXTERNAL IDIM 
INTEGER 11,12 
41=1988 
12=1929 
PRINT *, “The IDIM of i1,i2 is:’ 
PRINT *, IDIM(i1,i2) 
END 

Output: 


The IDIM of i1,i12 is: 
59 
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IDNINT 


IDNINT returns the nearest integer to an argument. It accepts a double precision 
argument and returns an integer result. 


The call-by-reference entry points are MLP$RIDNINT and IDNINT, and the 
call-by-value entry point is MLP$VIDNINT. 


The input domain for this function is the collection of all valid double precision 
quantities. The output range is included in the set of valid integer quantities. 
Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 

It is indefinite. 

It is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


If the argument is = 0, .5 is added to it, and the result is added to a special 
floating-point zero that forces truncation. If the argument is < 0, —.5 is added to it, 
and the result is added to a special floating-point zero that forces truncation. 


If the value of the argument is not in the range [-2**63 -— 2**15,2**63 -— 2**15], then 
the high order bits of the resulting integer are lost (the result is truncated in its 
leftmost position). 
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Example of IDNINT Called From FORTRAN 


Source Code: 


PROGRAM IDNINT_EXAMPLE 


EXTERNAL IDNINT 
DOUBLE PRECISION x 

x=999 .999d0 

PRINT *, “The nearest integer to x is:’ 
PRINT *, IDNINT(Xx) 

END 


Output: 


The nearest integer to x is: 
1000 
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INSB inserts bits from the first argument, x, into a copy of the fourth argument, y, as 
specified by the second and third arguments, il and i2; that is, INSB(x, il, i2, y) 
inserts bits from x starting with position il with length of i2 into a copy of y. It 
accepts any type except character for arguments x and y, and accepts integer for 
arguments il and i2. The result is boolean. 


If x or y is of type double precision or complex, only the first word is used. The result 
is returned with a zero-filled second word; however, for double precision the first 4 
bytes of the first word are duplicated in the second word. This duplication preserves 
the exponent in the second word. The following FORTRAN example uses function INSB 
with double precision arguments to illustrate the zero-filled second word and the 
duplication of the exponent 1111 in the second word. 


Source Code: 


PROGRAM INSB_EXAMPLE 


EXTERNAL INSB 

DOUBLE PRECISION d1,d2,d3 
BOOLEAN x(2),y(2),z2(2) 
EQUIVALENCE (x(1),d1),(y(1),d2),(z(1) ,d3) 
x(1)=Z" 1234567890ABCDEF" 
X(2)=Z"FEDCBA098765432 1" 
y(1)=Z"1111111111111111" 
y(2)=Z"2222222222222222" 
d3=insb(d1, 16, 16,d2) 

PRINT *,x(1),x(2),y(1),y(2). 
PRINT *,2(1),2(2) 

END 


Output: 


Z"1234567890ABCDEF" Z"FEDCBA0987654321" 2"1111111111111111" 2"2222222222222222" 
Z2°1111CDEF 11111111" Z"1111000000000000" 


Arguments x and y must be byte aligned and be at least 64 bits in length. The 
argument used is the leftmost 64 bits of each x and y. Argument il indicates first bit 
position in y for insertion. Argument i2 indicates the rightmost number of bits taken 
from x to be inserted into y. 


The call-by-reference entry points are MLP$RINSB and INSB, and the call-by-value 
entry point is MLP$VINSB. 


The input domain for this function is such that il is greater than or equal to 0 and 
less than 64; i2 is greater than or equal to 0; and il + i2 is less than or equal to 64. 
If i2 = 0, the result is the value of y. The data type of arguments x and y is not 
significant to the processing of this function. The output range is included in the set of 
valid boolean quantities. 
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Call-By-Reference Routine 
The arguments il and i2 are checked upon entry. They are invalid if: 
il is less than zero. 
i2 is less than zero. 
il is greater than or equal to 64. 
il + i2 is greater than 64. 
If the arguments are invalid, a diagnostic message is displayed. If the arguments are 


valid, the call-by-value routine is branched to, and the result of the function is 
returned to the calling program. 


Call-By-Value Routine 
The inserted bits from the first argument, x, into a copy of the fourth argument, y, as 


specified by the second and third arguments, il and i2, are returned. The leftmost 64 
bits of x and y are used. 


Example of INSB Called From FORTRAN 


Source Code: 


PROGRAM INSB_EXAMPLE 


Cc 

EXTERNAL INSB 
REAL x,y 
INTEGER ii, i2 
x=Z"432 1FEDCBA987654" 
y=Z"0" 
i1=0 
12=48 
PRINT *, “The inserted bits from x, as specified by ” 
PRINT *, “ il and i2, into a copy of y are: ’ 
PRINT *, INSB(x,i1,i2,y) 
END 

Output: 


The inserted bits from x, as specified by 
il and i2, into a copy of y are: 
Z"FEDCBA9876540000" 
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ISIGN transfers the sign of one argument to another argument. It accepts two integer 
arguments and returns an integer result. The result is a copy of the first argument 
with the sign of the second argument. 


The call-by-reference entry points are MLP$RISIGN and ISIGN, and the call-by-value 
entry point is MLP$VISIGN. 


The input domain for this function is the collection of all valid integer quantities. The 
output range is included in the set of valid integer quantities. 


Call-By-Reference Routine 


No errors are generated by ISIGN. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 
The exclusive OR of the first argument, along with the second argument, is shifted to 


extend its sign bit across a word to produce a mask. The mask is then subtracted from 
the exclusive OR of the mask and argument to form the result. 


8-146 Math Library 60486513 H 


Example of ISIGN Called From FORTRAN 


Source Code: 


PROGRAM ISIGN_EXAMPLE 


Cc 

EXTERNAL ISIGN 
INTEGER i1, i2 
i1=-140 
12=750 
PRINT *, “The ISIGN of i1, i2 is:’ 
PRINT *, ISIGN(i1, i2) 
END 

Output: 


The ISIGN of i1, i2 is: 
140 
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ITOD performs exponentiation for program statements that raise double precision 
quantities to double precision exponents. It accepts two double precision arguments and 
returns a double precision result. ITOD also accepts compiler-generated calls (for 
example, the FORTRAN and Ada compilers provide the exponentiation operator **).. 


The call-by-reference entry points are MLP$RITOD and ITOD, and the call-by-value 
entry point is MLP$VITOD. 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a nonnegative integer quantity and y is a double precision quantity. If x is equal to 
zero, then y must be greater than zero. The output range is included in the set of 
valid double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. The argument pair - invalid if: 

y is indefinite. 

y is infinite. 

x is equal to zero and y is less than or equal to zero. 

x is negative. 
If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 


it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 0. 


Upon entry, the integer argument is converted to double precision, and the routine 
calls DLOG to compute log(x), and DEXP to compute exp(y*log(x)). 
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Error Analysis 


See the description of function DTOD. 


Effect of Argument Error 


If a small error e occurs in the exponent, the error in the result r is given 
approximately by r*e*log(b), where b is the base. 


Example of ITOD Called From FORTRAN 


Source Code: 


PROGRAM ITOD_EXAMPLE 


INTEGER i 
DOUBLE PRECISION d, d1, itod 

i=2 

d=10.0d0 

d1=ITOD(i,d) 

PRINT *, “The ITOD of i and d is:’ 
PRINT *, dl 

END 


Output: 


The ITOD of i and d is: 
1024. 
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ITOI 


ITOI performs exponentiation for program statements that raise double precision 
quantities to double precision exponents. It accepts two double precision arguments and 
returns a double precision result. ITOI also accepts compiler-generated calls (for 
example, the FORTRAN and Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RITOI and ITOI, and the call-by-value 
entry point is MLP$VITOI. 


The input domain for this function is the collection of all valid integer pairs (x,y) such 
that the absolute value of x**y is less than 2**63. If x is equal to zero, then y must 
be greater than zero. The output range is included in the set of valid integer . 
quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. The argument pair is invalid if: 

x is zero and y is zero or negative. | 
If the argument pair is invalid, zero is returned, and a diagnostic ‘message is displayed. 
If the argument pair is valid, the call-by-value routine is called, and the result of the 
computation is returned to the call-by-reference routine. The result is checked. If the 


result is infinite, it is invalid, and a diagnostic message is displayed. If the result is _ 
valid, it is returned to the calling program. 


Call-By-Value Routine 


The arguments are checked to determine whether the exponentiation conforms to a 
special case. If it does, the proper value is immediately returned, or if the special case 
is an error condition, a hardware exception condition is forced. The special cases are: 


0**0 = error 
O**J = error if J <0O 


ey = 1 
~1**J = +1 or -1 (J even or odd) 
I**Q = 1 


I**y=O0 if J <0O 


If the exponentiation does not fit any special case, the algorithm listed below is used 
for the computation. 


An x represents the base and a y represents the exponent. If x has binary 
representation 000... .000i(n)i(n-1) ...i(i)i(0), where each i(j)(0 = j = n) is 0 or 1, then: 


y = 1(0)*2**0 + i1(1)*#2**1 + 1... + i(nm)*2**n 
n = (log(2)y) = greatest integer not exceeding log(2)y 
Then: 


x**y = prod[x**2**j : 0 < j <n and i(j) = 1] 
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The numbers x = x**0, x**2**0, x**2, x**4, ..., x**(2)**n are generated during the 
computation by successive squarings, and the coefficients i(0), ...., i(n) are obtained as 
sign bits of successive right shifts of y within the computer. A running product is 
formed during the computation so that smaller powers of x can be discarded. The 
computation then becomes an iteration of the algorithm: 


x**y = 1, if y = 1, and x not= 0 


= (x*x)**(y/2), if y > 0 and y is even 
= (x*x)**((y-1)/2)*x, if y > 0 and y is odd 


Example of ITOI Called From FORTRAN 


Source Code: 


PROGRAM ITOI_EXAMPLE 


Cc 

INTEGER i1, i2, ix 
i1=2 
i2=8 
ix=ITOI(i1, 12) 
PRINT *, “The ITOI of i1 and i2 is:’ 
PRINT *, ix 
END 

Output: 


The ITOI of i1 and i2 is: 
256 
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ITOX performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. ITOX also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RITOX and ITOX, and the call-by-value 
entry point is MLP$VITOX. 


The input domain for this function is the collection of all valid pairs (x,y), where x is 

a nonnegative integer quantity, y is a real quantity, and x**y is a valid quantity. If x 
is equal to zero, then y must be greater than zero. The output range is included in the 
set of valid, nonnegative real quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. The argument pair is invalid if: 
y is indefinite. 
y is infinite. 
X is equal to zero and y is less than or equal to zero. 
x is negative. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 1 


Upon entry, x is converted to real, and the routine calls XTOX to compute the result. 
Zero is returned if the base is zero and the exponent is positive. 


Error Analysis 


See the description of function XTOX. 


Effect of Argument Error 


If a small error e occurs in the exponent x, the error in the result r is given 
approximately by r*e*log(n), where n is the base. 
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Example of ITOX Called From FORTRAN 


Source Code: 


Output: 


PROGRAM ITOX_EXAMPLE 


INTEGER i 

REAL x, r, itox 

j=2 

x=8.8 

r=ITOX(i,x) 

PRINT *, “The ITOX of i and x is:’ 
PRINT *,r 

END 


The ITOX of i and x is: 
445 .7218884076 
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ITOZ performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. ITOZ also accepts compiler-generated calls (for example, the FORTRAN and Ada 
compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RITOZ and ITOZ, and the call-by-value 
entry point is MLP$VITOZ. . . 


The ITOZ vector math function is divided into three routines having three ‘separate 
entry points defined as follows: . 


ITOZ(scalar,vector) = MLP$ITOZV 
ITOZ(vector,scalar) = MLP$IVTOZ 
ITOZ(vector,vector) = MLP$IVTOZV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a nonnegative nonzero integer quantity and y is a complex quantity. If x is equal to 
zero, then the real part of y must be greater than zero, and the imaginary part must 
be equal to zero. The output range is included in the set of valid complex quantities. 
Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 

y is indefinite. 

y is infinite. 


x is equal to zero, and the real part of y is zero or negative, or the imaginary part 
of y is not equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
If n is a positive integer, and x and y are real, then: 
n**(x + i*y) = exp(x*log(n))*cos(y*log(n)) + i*exp(x*log(n))*sin(y*log(n) ) 


Upon entry, n is converted to complex, and the routine calls ZTOZ to compute the 
result. 
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Vector Routine 

The argument pair.(x,y) is checked upon entry. It is invalid if: 
y is indefinite. 
y is infinite. 


x is equal to zero, and the real part of y is zero or negative, or the imaginary part 
of y is not equal to zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 
A group of 10,000 arguments was chosen randomly from the interval 


([-1.0,1.0] ,[-1.0,1.0]) and ({[-1.0,1.0],[-1.0,1.0]). The maximum relative error of these 
arguments was found to be 1.7431E-11. 


Effect of Argument Error 


If a small error e(z) = e(x) + i*e(y) occurs in the exponent z, the error in the result 
w is given approximately by w*log(n)*e(z). 


Example of ITOZ Called From FORTRAN 


Source Code: 


PROGRAM ITOZ_EXAMPLE 


C 

INTEGER i 
COMPLEX z, zeta, itoz 
ji = 50 
z = (5.0, -1) 
zeta = ITOZ(i,z) 
PRINT *, “The ITOZ of i and z is:’ 
PRINT *, zeta 
END 

Output: 


The ITO0Z of i and Z is: 
(-224253443.769, 217638790. 1035) 
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MOD 


MOD computes the remainder of the ratio of two arguments. It accepts two integer 
arguments and returns an integer result. 


The call-by-reference entry points are MLP$RMOD and MOD, and the call-by-value | 
entry point is MLP$VMOD. 


The input domain for this function is the collection of all valid integer pairs (x,y), 
where x is an integer quantity and y is a nonzero integer quantity. The output range 
is included in the set of valid integer quantities. 


Call-By-Reference Routine 
Upon entry, the argument pair (x,y) is checked. It is invalid if: 
y is equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is branched to, and the result is returned. 


Call-By-Value Routine 


Upon entry, the arguments x and y are converted to real, the quotient x/y is formed, 
and the result is multiplied by y and then subtracted from x. 
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Example of MOD Called From C 


Source Code: 


main() 
{ 
int i = 88; 
int j = 8; 
int k; 
/* Use the left bit-shift operator (<<) to left justify the address 


7 


16 bits. This is necessary because the MOD Math Library function 
expects left-justified addresses. 


k = MOD( (int) (&i)<<16,(int) (&j)<<16); 
printf (" The Mod of 83 and 8 is: %d", k); 
exit (0); 


Output: 


The Mod of 83 and 8 is: 


3 


Example of MOD Called From FORTRAN 


Source Code: 


PROGRAM MOD_EXAMPLE 


C 
INTEGER i1, i2 
{1=83 
i2=8 
PRINT *, “The MOD of i1 and i2 is:’ 
PRINT *, MOD(i1,i12) 
Output: 


Tne MOD of i1 and i2 is: 


3 
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NINT 


NINT finds the nearest integer to an argument. It accepts a real argument and returns 
an integer result. 


The call-by-reference entry points are MLP$RNINT and NINT, and the call-by-value 
entry point is MLP$VNINT. 


The input domain for this function is the collection of all valid real quantities. The 
output range is included in the set of valid integer quantities. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is branched to, and the result of the computation is returned 
to the calling program. 


Call-By-Value Routine 


If the argument is = 0, .5 is added to it, or if the argument is < 0, -.5 is added to 
it. This sum is converted from floating-point to integer and returned. 


Example of NINT Called From FORTRAN 


Source Code: 


PROGRAM NINT_EXAMPLE 


EXTERNAL NINT = 

INTEGER i1,i12 

REAL x,y i 
x=100. 1234 

y=12.12 

i1=NINT(x) 

i12=NINT(y) 

PRINT *, “The nearest integers to x and y are:’ 
PRINT *, NINT(Xx) 

PRINT *, NINT(y) 

END 


Output: 
The nearest integers to x and y are: 


100 
12 
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RANF 


RANF generates the next random number in a series of random numbers. It accepts a 
- dummy argument and returns a real result. 


The call-by-reference entry points are MLP$RRANF and RANF, and the call-by-value 
entry point is MLP$VRANF. 


There is no input domain to this function. The output range is included in the set of 
positive real quantities less than 1.0. 


Call-By-Reference Routine 


No errors are generated in RANF. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 
RANF uses the multiplicative congruential method modulo 2**48. The formula is: 
x(n + 1.0) = a*x(n) (mod 2**48) 


The library holds a random seed (mlv$initial_seed) and a multiplier (mlv$random_ 
multiplier). The random seed can be changed to any valid seed value prior to calling 
RANF by use of the function RANSET (described later in this chapter). Upon entry at 
RANF, the random seed is multiplied in double precision by mlv$random_multiplier to 
generate a 96-bit product, which is the new seed partially normalized by one bit. This 
result is then denormalized. The lower 48 bits are formed with an exponent that yields 
a result between 0 and 1.0 to become the new random seed (mlv$random_seed). The 
current seed for the task is updated with the newly formed unnormalized seed. The 
seed is used to generate subsequent random numbers. The default initial value of 
mlv$initial_seed is 40002BC68CFE166D hexadecimal. The new random seed is 
normalized and returned as the random number. 


The multiplier (mlv$random_ multiplier) is constant and has a value of 
40302875A2E7B175 hexadecimal. This multiplier passes the Coveyou-MacPherson test, 
the auto-correlation test with lag = 100, the pair triplet test, and other statistical tests 
for randomness.° 


6. Algorithm and Constants, Copyright 1970 by Krzysztof Frankowski, Computer Information and Control 
Science, University of Minnesota. 
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Example of RANF Called From Ada 


Source Code: 
package RANDOM_LIBRARY is 


function RANF return FLOAT; 
pragma INTERFACE (MATH_LIBRARY, RANF); 


procedure RANGET (RESULT : in out FLOAT); 
pragma INTERFACE (MATH_LIBRARY, RANGET); 


procedure RANSET (VALUE : in out FLOAT); 
pragma INTERFACE (MATH_LIBRARY, RANSET); 


end RANDOM_ LIBRARY; 


with RANDOM_LIBRARY; use RANDOM_LIBRARY; 
with TEXT_IO; use TEXT_IO; 


procedure RANDOM is 


x1 : FLOAT; 
x2 : FLOAT; 


package FLT_IO is new FLOAT_IO (FLOAT); 
use FLT_IO; 


begin 


PUT_LINE ("Begin"); 

x1 := 0.7777; 

PUT ("Call RANSET with : "); PUT (x1); NEW_LINE; 
RANSET (x1); 

RANGET (x2); 

PUT ("RANGET returned : "); PUT (x2); NEW_LINE; 
xl := RANF; 

x2 := RANF; 

PUT ("RANF returned : "); PUT (x1); NEW_LINE; 
PUT ("RANF returned : "); PUT (x2); NEW_LINE; 
PUT_LINE ("End"); 


end RANDOM; 


Output: 


Begin 

Call RANSET with : 7.777000000000E01 
RANGET returned : 7.777000000000E01 
RANF returned : 8.022426980171E-01 
RANF returned : 5.003749989168E-02 
End 
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Example of RANF Called From C 


Source Code: 


RANF 


/* This C program uses the RANF function to compute 10 random numbers 
between 0 and 1. 


5a 


#define MAX 10 


main() 
{ 


int count = 


int random_number; /* Random number generated by RANF. 


0; 


int ran_num_add; 


for (count=0; count < MAX; ++count) 


{ 


/* loop counter 


random_number = RANF(); 


“/ 


printf("Random number %d is %f.\n", count, random_number) ; 


Output: 


Random 
Random 
Random 
Random 
Random 
Random 
Random 
Random 
Random 
Random 


number 
number 
number 
number 
number 
number 
number 
number 
number 
number 


OMAN OU AP WHY = CO 


-- Program exit 
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-is 


is 
is 
is 
is 
is 


is 
is 
is 
is 


oooooo0o0oo;o 


code 


-580114. 
-950513. 
- 786371. 
. 297620. 
-453700. 
.006262. 
.275736. 
.305651. 
-689101. 
. 382662. 


value was 10. 


Function Descriptions 8-161 


‘RANGET 


RANGET 


RANGET is a callable program procedure that returns the current random number 
seed of a task. It accepts a real argument. 


The call-by-reference entry points are MLP$RRANGET and RANGET. There is no 
call-by-value routine for RANGET. . 


The result is returned through parameter n and is a positive real quantity in the 
interval (0,1.0). 


Call-By-Reference Routine 


RANGET returns the current seed, between 0 and 1, of the random number generator. — 
The value returned might not be normalized. This seed can be used to restart the 
random sequence at exactly the same point. The current seed is mlv$random_seed. 


Call-By-Value Routine 


There are no call-by-value entry points for RANGET. 


Example of RANGET 


See the example Ada program in the RANF description in this chapter for an example 
of a RANGET call. 
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RANSET 


RANSET is a callable program procedure that sets the seed of the random number 
generator. It accepts a real argument and returns a real result. 


The call-by-reference entry points are MLP$RRANSET and RANSET. There is no 
call-by-value routine. 


The input domain for this procedure is the collection of all possible full word bit 
patterns. There is no output. 


Call-By-Reference Routine 


RANSET uses the value passed to it to form a valid seed for the random number 
generator. If the argument is zero, the seed is set to its initial value (mlv$initial_seed) 
at load time. Otherwise, the value passed has its exponent set to 4000 hexadecimal, 
and the coefficient is made odd. This value is then saved and becomes the new seed 
(mlv$random seed) for the task. 


Example of RANSET 


See the example Ada program in the RANF description in this chapter for an example 
of a RANSET call. 
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SIGN 


SIGN transfers the sign from one argument to another argument. It accepts two real 
arguments and returns a real result. The result is a copy of the first argument with 
the sign of the second argument. 


The call-by-reference entry points are MLP$RSIGN and SIGN, and the call-by-value 
entry point is MLP$VSIGN. 


The input domain for this function is the collection of all valid real quantities. The 
output range is included in the set of valid real quantities. 


Call-By-Reference Routine 


No errors are generated by SIGN. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The sign bit of the second argument is inserted into the sign bit of the first argument. 
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Example of SIGN Called From FORTRAN 


Source Code: 


PROGRAM SIGN_EXAMPLE 


EXTERNAL SIGN 

REAL x, y 

x=- 180.0 

y=90.0 

PRINT *, “The SIGN of x, y is:’ 
PRINT *, SIGN(x,y) 

END 


Output: 


The SIGN of x, y is: 
180. 
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SIN 


SIN computes the sine function. It accepts a real argument and returns a real result. 


The call-by-reference entry points are MLP$RSIN and SIN, the call-by-value entry 
point is MLP$VSIN, and the vector entry point is MLP$SINV. 


The input domain for this function is the collection of all valid real quantities whose 


absolute value is less than 2**47. The output range is included in the set of valid real 
quantities in the interval [-1.0,1.0]. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 
If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 


the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


See the description of function COS. 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 
The function SIN was tested against 3*SIN(x/3) - 4*SIN(x/3)**3. Groups of 2,000 


arguments were chosen randomly from given intervals. Statistics on relative error were 
observed. Table 8-22 shows a summary of these statistics. 


Table 8-22. Relative Error of SIN 


Root Mean 
Interval From Interval To Maximum Square 
0.0000E + 00 1571E+01 .8305E-14 .2874E-14 
.1885E + 02 .2042E+02 .1355E-13 .3168E-14 
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Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e*cos(x) for sin(x) and —e*sin(x) for cos(x). 


Example of SIN Called From FORTRAN 


Source Code: 


PROGRAM SIN_EXAMPLE 


C 
REAL x 
x=0.5 
PRINT *, “The SIN Of x is:’ 
PRINT *, SIN(x) 
END 
Output: 


The SIN of x is: 
- 4794255386042 
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SIND 


SIND computes the sine function of an argument in degrees. It accepts a real argument 
and returns a real result. a 


The call-by-reference entry points are MLP$RSIND and SIND, the call-by-value entry 
point is MLP$VSIND, and the vector entry point is MLP$SINDV. 


The input domain for this function is the collection of all valid real quantities whose 
absolute value is less than 2**47. The output range is included in the set of valid real 
quantities in the interval [-1.0,1.0]. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. | 
It is infinite. 
Its absolute value is greater than or equal to O47, 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


The result is put in the interval [-45,45] by finding the nearest integer, n, to x/90, and 
subtracting n*90 from the argument. The reduced argument is then multiplied by 
pi/180. The appropriate sign is copied to the value of the appropriate function, sine or 
cosine, as determined by these identities: 


sin(x + 360 degrees) = sin(x) 
sin(x + 180 degrees) = -sin(x) 
sin(x + 90 degrees) = cos(x) 
sin(x - 90 degrees) = -cos(x) 
cos(x + 360 degrees) = cos(x) 
cos(x + 180 degrees) = -cos(x) 
cos(x + 90 degrees) = -sin(x) 
cos(x - 90 degrees) = sin(x) 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The reduction to (-45,+45) is exact; the constant pi/180 has relative error 1.87E-15, 
and multiplication by this constant has a relative error 5.33E-15, and a total error of 
6.7E-15. Since errors in the argument of SIN and COS contribute only pi/4 of their 
value to the result, the error due to the reduction and conversion is at most 5.26H-15 
plus the maximum error in SINCOS over (—pi/4,+ pi/4). The maximum relative error 
observed for a group of 10,000 arguments chosen randomly in the interval [0,360] was 
.1403E-13 for SIND and .7105E-14 for COSD. 


Effect of Argument Error 


Errors in the argument x are amplified by x/tan(x) for SIND and x*tan(x) for COSD. 
These functions have a maximum value of pi/4 in the interval (-45,+45) but have 
poles at even (SIND) or odd (COSD) multiples of 90 degrees, and are large between 
multiples of 90 degrees if x is large. 


Example of SIND Called From FORTRAN 


Source Code: 


PROGRAM SIND_EXAMPLE 


Cc 
REAL x 
x=0.5 
PRINT *, “The SIND of x is:’ 
PRINT *, SIND(x) 
END 
Output: 


The SIND of x is: 
.008726535498374 
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SINH 


SINH computes the hyperbolic sine function. It accepts a real argument and returns a 
real result. 


The call-by-reference entry points are MLP$RSINH and SINH, the call-by-value entry 
point is MLP$VSINH, and the vector entry point is MLP$SINHV. 


The input domain for this function is the collection of all valid real quantities whose 
absolute value is less than 4095*log(2). The output range is included in the set of all 
valid real quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 4095*log(2). 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 


The formulas used to compute sinh(x) are: 


Xx n*log(2) + a, where Jal < 1/2*109(2) 

and n is an integer 

sinh(x) = (cosh(a) + sinh(a))*2**(n-1), when n > 25 
sinh(x) = sinh(a), when n = 0, otherwise, 


sinh(x) (c - s)*2**(n-1) + (c + s)*2**(-n-1) 


where: 


sinh(a) = a + s(3)*a**3*(s(5) + TOP/(BOT - a**2)) 
cosh(a) = 1.0 + a**2*(.5 + a**2*(c(4) + a**2*(c(6) + 
c(10)*a**2*(c(8) + a**2)))) 


Constants used in the algorithm are: 


s(3) = . 166 666 666 666 935 58 
s(5) = -.005 972 995 665 652 368 
TOP = 1.031 539 921 161 

BOT = 72.103 746 707 22 

c(4) = .041 666 666 666 488 081 
c(6) = .001 388 888 895 231 804 5 
c(8) = 89.754 738 973 150 22 

c(10) = 2.763 250 805 803*10**-7 
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The algorithm used is: 
a. u= [xl 


b. n= (u/log(2) + .5) = nearest integer to u/log(2) R 
w = U - n*jog(2), where the right-hand expression is evaluated in double 


precision 
c. s =w +t w**3(s(3) + w**2(s(5) + TOP/(BOT - w**2))) 
d = w**2(1/2 + w**2(c(4) + w**2(c(6) + w**2(c(8) + w**2)*c(10)))) 
a = (1.0 + d - s)*2**(-n-1) 
b=dts 


d. c = (1/4 + (1/4 + b))*2**(n-1) + (2**(n-3) + (2**(n-3) - a)) 
XF = c with the sign of x 


e. Return 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 4095*log(2). 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


60486513 H Function Descriptions 8-171 


SINH 


Error Analysis 


Groups of 2,000 arguments were chosen randomly from given intervals. Statistics on 
relative error were observed. Table 8-23 shows a summary of these statistics. 


Table 8-23. Relative Error of SINH 


Test Interval From 


SINH(x) against 0.0000E + 00 
Taylor series 
expansion of SINH(x) 


SINH(x) against .3000E +01 
c*(SINH (x + 1) + 
SINH(x - 1)) 


Effect of Argument Error 


Interval To Maximum 


.5000E+00 .3374E-13 


.2838E+04, .2894E-13 


Root Mean 
Square 


.9969E-14 


.9979E-14 


If a small error e occurs in the argument x, the resulting error in sinh(x) is given 


approximately by cosh(x)*e. 
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Example of SINH Called From FORTRAN 


Source Code: 


PROGRAM SINH_EXAMPLE 


Cc 
REAL x 
x=0.5 
PRINT *, ‘The SINH of x is:’ 
PRINT *, SINH(x) 
END 
Output: 


The SINH of x is: 
.5210953054938 
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SQRT 


SQRT computes the square root function. It accepts a real argument and returns a real 
result. 


The call-by-reference entry points are MLP$RSQRT and SQRT, the call-by-value entry 
point is MLP$VSQRT, and the vector entry point is MLP$SQRTV. 


The input domain for this function is the collection of all valid, nonnegative real 
quantities. The output range is included in the set of valid, nonnegative real quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is negative. 
If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 


the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 
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Call-By-Value Routine 


_If x is valid, let y be a real number in [0.5, 2) and n an integer such that x = 
y*2**(2*n). Then SQRT(x) is evaluated by: 


SQRT(x) = SQRT(y)*2**n 


Then SQRT(y) is approximated to 48 bits of precision by applying one iteration of 
Heron’s rule to an initial approximation which is accurate to at least 24 bits of 
precision. The initial approximation is computed by dividing the interval [0.5, 2) into 
the following 64 subintervals: : 


[32/64, 33/64) 


(63/64, 64/64) 
[32/32, 33/32) 


[63/32, 64/32) 


The coefficients of these 64 minimax approximations are stored in three tables p0, pl, 
and p2 such that: . 


zi = poli] + pilil*y + p2Lil*y**2 


is the quadratic minimax approximation to the square root of y over the subinterval 
whose index is i. The required initial approximation is obtained by calculating the 
index i of the subinterval that contains y and then evaluating the above quadratic 
polynomial so that z1 approximates SQRT(y) to at least 24 bits of precision. 


Using Heron’s rule, the computation: 
twoz2 = 21 + y/21 

approximates SQRT(y) to 48 bits precision followed by the computation: 
SQRT(x) = twoz2*2**(n - 1) 


which approximates SQRT(x) to 48 bits of precision. 
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Vector Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
It is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The function SQRT was tested in the form SQRT(x*x) - x. Groups of 2,000 arguments 
were chosen randomly from given intervals. Statistics on relative error were observed. 
Table 8-24 shows a summary of these statistics. 


Table 8-24. Relative Error of SQRT 


Root Mean 
Interval From Interval To Maximum Square 
.1000E+01 .1414E+01 .7099E-14 .5677E-14 
.7071E+ 00 1000E+01 .5023E-14 .4106E-14 


Effect of Argument Error 


For a small error e in the argument y, the amplification of absolute error is 
e/(2* sqrt(y)). . 
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Example of SQRT Called From FORTRAN 


Source Code: 


PROGRAM SQRT_EXAMPLE 


C 
REAL x, xe 
x=22500.0 
xe=SQRT(x*x)- x 
PRINT *, “The SQRT of x is:’ 
PRINT *, SQRT(x) 
PRINT *, ’The calculated error of the SQRT of x is:’ 
PRINT *, xe 
END 
Output: 
The SQRT of x is: 
150. 
The calculated error of the SQRT of x is: 
0. 
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SUMI1S 


SUMIS returns the sum (or number) of 1 bits in a word. (The number of bits in a 
NOS/VE word is always 64.) It accepts any type of argument except character and 
logical and returns an integer result. If the argument is of type double precision or 
complex, only the first word is used. 


The call-by-reference entry points are MLP$RSUMIS and SUMIS, and the call-by-value 
entry point is MLP$VSUMIS. 


The input domain for this function is the collection of all valid boolean, real, complex, 


integer, or double precision quantities. Character and logical arguments are not 
allowed. The output range is included in the set of valid integer quantities. 


Call-By-Reference Routine 


No errors are generated by SUMIS. The call-by-reference routine branches to the 
call-by-value routine. 


Call-By-Value Routine 


The number of bits in a word is returned. The argument can be any type except 
character and logical. 
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Example of SUM1S Called From FORTRAN 


Source Code: 


PROGRAM SUM1S_EXAMPLE 


Cc 
REAL x 
X=Z" 432 1FEDCBA987654" 
PRINT *, “The SUM1S of x is:’ 
PRINT *, SUM1S(x) 
END 
Output: 


The SUM1S of x is: 
33 
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TAN 


TAN computes the trigonometric circular tangent function. It accepts a real argument 
and returns a real result. 


The call-by-reference entry points are MLP$RTAN and TAN, the call-by-value entry 
point is MLP$VTAN, and the vector entry point is MLP$TANV. 


The input domain for this function is the collection of all valid real quantities whose 
absolute value is less than 2**47. The output range is included in the set of valid real 
quantities. 


Call-By-Reference Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to O**A7, 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, . 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 
The evaluation is reduced to the interval [-.5,.5] by using the identities: 
1. tan(x) = tan(x + k*pi/2), if k is even 
2. tan(x) = -1.0/tan(x + pi/2) 
in the form: 
3. tan(x) = tan((pi/2)*(x*2/pi + k)), if k is even 
4. tan(x) = -1.0/tan((pi/2)*(x*2/pi + 1.0)) 


An approximation of tan(pi/2*y) is used. The argument is reduced to the interval 
[-.5,.5] by subtracting a multiple of pi/2 from x in double precision. 


The rational form is used to compute the tangent of the reduced value. The function 
tan((pi/2)*y) is approximated with a rational form (7th order odd)/(6th order even), 
which has minimax relative error in the interval [-.5,.5]. The rational form is 
normalized to make the last numerator coefficient 1 + e, where e is chosen to— 
minimize rounding error in the leading coefficients. 


Identity 4 is used if the integer subtracted is odd. The result is negated and inverted 
by dividing —Q/P instead of P/Q. 
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Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


The range reduction, the final add in each part of the rational form, the final multiply 
in P, and the divide dominate the error. Each of these operations contributes directly 
to the final error, and each is accurate to about 1/2 ulp. 


The function TAN was tested against 2*TAN(x/2)/((1 -— TAN(x/2)**2). Groups of 2,000 
arguments were chosen randomly from given intervals. Statistics on relative error were 
observed. Table 8-25 shows a summary of these statistics. 


Table 8-25. Relative Error of TAN 


Root Mean 
Interval From Interval To Maximum Square 
0.0000E + 00 .7854E+00 .2177E-13 .5613E-14 
.1885E + 02 .19683E+02 .1993E-13 .5617E-14 
.2749E +01 .38534E+01 .2190E-13 .7286E-14 


Effect of Argument Error 
For small errors in the argument x, the amplification of absolute error is sec(x)**2, 


and that of relative error is x/(sin(x)*cos(x)), which is at least 2x and can be arbitrarily 
large near a multiple of pi/2. 


Example of TAN Called From FORTRAN 


Source Code: 


PROGRAM TAN_EXAMPLE 


C 
REAL x 
=0.5 
PRINT *, “The TAN Of x is:’ 
PRINT *, TAN(x) 
END 
Output: 


The TAN of x is: 
-54630224898438 
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TAND 


TAND computes the trigonometric tangent for an argument in degrees. It accepts a 
real argument and returns a real result. 


The call-by-reference entry points are MLP$RTAND and TAND, the call-by-value entry 
point is MLP$VTAND, and the vector entry point is MLP$TANDV. 


The input domain for this function is the collection of all valid real arguments whose 
absolute value is less than 2**47, excluding odd multiples of 90. The output range is 
included in the set of valid real quantities. 


Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 


Its absolute value is greater than or equal to 2**47. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
call-by-reference routine. The result is checked. If the result is infinite, it is invalid, 
and a diagnostic message is displayed. If the result is valid, it is returned to the 
calling program. 


Call-By-Value Routine 


The result is put in the interval [-45,45] by finding the nearest integer n to x/90, and 
subtracting n*90 from the argument. The reduced argument is then multiplied by 
pi/180. The routine calls TAN to compute the tangent, and if the multiple n of 90 is 
odd, the result is negated and inverted by using the identities: 


180 degrees) = tan(x) 
90 degrees) = -1/tan(x) 


tan(x 


+ 
tan(x + 


Vector Routine 
The argument is checked upon entry. It is invalid if: 
It is indefinite. 
It is infinite. 
Its absolute value is greater than or equal to 2**47. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The reduction to (-45, +45) is exact; the constant pi/180 has a relative error of 
1.37E-15, and multiplication by this constant has a relative error of 5.833E-15, so the 
total error is 6.7E-15. The maximum relative error observed for 10,000 arguments 
chosen randomly in the interval [0,360], was .2130E-13. 

Effect of Argument Error 


Errors in the argument x are amplified at most by x/(sin(x)*cos(x)). This function has a 
maximum of pi/2 within (-45,+45) but has poles at all multiples of 90 degrees except 
zero. 


Example of TAND Called From FORTRAN 


Source Code: 


PROGRAM TAND_EXAMPLE 


C 
REAL x 
x=0.5 
PRINT *, “The TAND of x is:’ 
PRINT *, TAND(x) 
END 
Output: 


The TAND of x is: 
.008726867790759 
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TANH 


TANH computes the hyperbolic tangent function. It accepts a real argument and 
returns a real result. 


The call-by-reference entry points are MLP$RTANH and TANH, the call-by-value entry 
point is MLP$VTANH, and the vector entry point is MLP$TANHV. 


The input domain for this function is the collection of all valid real quantities. The 
output range is included in the set of valid real quantities in the interval [-1.0,1.0]. 
Call-By-Reference Routine 

The argument is checked upon entry. It is invalid if it is indefinite. 


If the argument is invalid, a diagnostic message is displayed. If the argument is valid, 
the call-by-value routine is called, and the result of the computation is returned to the 
calling program. 


Call-By-Value Routine 
The argument range is reduced to: 

tanh(x) = 1.0 - 2*(q - p)/((q - p) + 2**n*(q + p)) 
by the identities: 


tanh(-x) = -tanh(x) for x < 0 

tanh(x) = p(x)/q(x) approximately, in the interval [0,.55] 
tanh(x) = 1.0 - 2/(exp(2*x) + 1.0) 

exp(2*x) = (1.0 + tanh(x))/(1.0 - tanh(x)) 

exp(2*x) = 2**n*exp(2*(x - n*in(2)/2)) 


where n is chosen to be nint(x*2/In(2)) and p and q are evaluated on x — n*In(2)/2. 
This choice of n minimizes abs(x - n*¥ln(2)/2). 


When abs(x) = .55 = atanh(.5), the approximation p(x)/q(x) is used. When abs(x) > 
.55, the above range reduction is used. For abs(x) > 17.1, tanh(x) = sign(1.0,x). 


The approximation p/q is a minimax (relative error) rational form (5th order odd)/(6th 
order even). The range reduction is simplified by scaling the coefficients so that 
(x*2/In(2) - n) can be used instead of (x - n*In(2)/2). The coefficients are further scaled 
by an amount sufficient to reduce truncation error in the jeading coefficients without 
otherwise affecting accuracy. 


Vector Routine 
The argument is checked upon entry. It is invalid if it is indefinite. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The algorithm error due to finite approximation and coefficient truncation is 1.7E-15. 
For abs(x) < .55, the form p(x)/q(x) is used. The final operations z = x*2/In(2) and 
tanh(z*(p0+small))/(q0+small) dominate the error. For abs(x) > 1.25 the final 
subtraction (1.0 - small) dominates. 


For .55 = abs(x) = 1.25, the final operation is 1-R, where R becomes smaller as x 
approaches 1.25. Thus, the worst relative error is near .55, namely, (contribution from 
R) + (error in final sum), where R = 2*(q - p)((q — p) + 4*(q + p)). 


The function TANH was tested against (TANH(x - 1/8) + TANH(1/8))/(1 + TANH(x - 
1/8)*TANH(1/8)). Groups of 2,000 arguments were chosen randomly from given 
intervals. Statistics on relative error were observed. Table 8-26 shows a summary of 
these statistics. 


Table 8-26. Relative Error of TANH 


Root Mean 
Interval From Interval To Maximum Square 
.1250E + 00 .5493E+00 .4091E-13 .1085E-13 
.6743E + 00 .1768E+02 .2842E-13 3730E-14 


Effect of Argument Error 
For small errors in the argument x, the amplification of the absolute error is 


1/cosh**(x) and of relative error is x/(sinh(x)*cosh(x)). Both have maximum values of 
1.0 at zero and approach zero as x gets large. 


Example of TANH Called From FORTRAN 


Source Code: 


PROGRAM TANH_EXAMPLE 


C 
REAL x 
x=0.5 
PRINT *, “The TANH of x is:’ 
PRINT *, TANH(x) 
END 
Output: 


The TANH of x is: 
-462117 15726 
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XTOD performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. XTOD also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RXTOD and XTOD, and the call-by-value 
entry point is MLP$VXTOD. 


The XTOD vector math function is divided into three routines having three separate 
entry points defined as follows: 


XTOD(scalar,vector) = MLP$XTODV 
XTOD(vector,scalar) = MLP$XVTOD 
XTOD(vector,vector) = MLP$XVTODV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a nonnegative real quantity and y is a double precision quantity. If x is equal to zero, 
then y must be greater than zero. The output range is included in the set of valid 
double precision quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
Xx is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
x is negative. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result if valid, it is returned 
to the calling program. 


Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 0 


Upon entry, the argument x is converted to double precision, and all operations are 
carried out in double precision. The routine calls DLOG to compute log(x), and DEXP 
to compute exp(y*log(x)). 
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Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if, 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
xX is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


See the description of function DTOD. 


Effect of Argument Error 


If a small error e(b) occurs in the base b and a small error e(p) occurs in the exponent 
p, the error in the result r is given approximately by: 


r*(e(p)*log(b) + p*e(b)/b) 
Example of XTOD Called From FORTRAN 


Source Code: 


PROGRAM XTOD_EXAMPLE 


C 

REAL x 
DOUBLE PRECISION y, z, XTOD 
x=20.0 
y=140.0d0 
z=XTOD(x,y) 
PRINT *, “The XTOD of x and y is:’ 
PRINT *, 2 
END 

Output: 


The XTOD of xX and y is: 
1.393796574908 16394634598238E+182 
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XTOI 


XTOI performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. XTOI also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RXTOI and XTOI, and the call-by-value 
entry point is MLP$VXTOI. . 


The XTOI vector math function is divided into three routines having three separate 
entry points defined as follows: 


XTOI(scalar,vector) = MLP$XTOIV 
XTOI(vector,scalar) = MLP$XVTOI 
XTOI(vector,vector) = MLP$XVTOIV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a real quantity and y is an integer quantity. If x is equal to zero, then y must be 
greater than zero. The output range is included in the set of valid real quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 

X is indefinite. 

X is infinite. 

x is equal to zero and y is less than or equal to zero. 
If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 


it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 
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Call-By-Value Routine 


The arguments are checked to see whether the exponentiation conforms to a special 
case. If it does, the proper value is immediately returned. If the special case is an 
error condition, an error message is displayed. The special cases are: 


x indefinite = error 


x infinite = error 

0**0 = error 

x**} = 1.0 if i = 0 and x > 0 
x**j = 1.0/x**-i if i <0 

x = 0 = error if i <0 


If the exponentiation is not a special case, the following algorithm is used. 


Starting with the second most significant bit, the binary representation of i is scanned 
from left to right. The result is initialized to x. For each scanned bit, the result is 
squared. If the scanned bit is 1, the result is multiplied by x. 


Effect of Argument Error 


If a small error e occurs in the base b, the error in the result will be given 
approximately by n*b**(n—1)*e, where n is the exponent (integer argument of the 
function). 


Example of XTOI Called From FORTRAN 


Source Code: 


PROGRAM XTOI_EXAMPLE 


INTEGER i 

REAL x, XTOI 

i1=3 

x=10.0 

PRINT *, “The XTOI of x and i is:’ 
PRINT *, XTOI(x,i) 

END 


Output: 


The XTOI of x and i is: 
1000. 
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XTOX performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. XTOX also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RXTOX and XTOX, and the call-by-value 
entry point is MLP$VXTOX. 


The XTOX vector math function is divided into three routines having three separate 
entry points defined as follows: 


XTOX(scalar,vector) = MLP$XTOXV 
XTOX(vector,scalar) = MLP$XVTOX 
XTOX(vector,vector) = MLP$XVTOXV 


The input domain for this function is the collection of all valid real pairs (x,y), where 
x is a nonnegative quantity and x**y is a valid quantity. If x is equal to zero, then y 
must be greater than zero. The output range is included in the set of valid, 
nonnegative real quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
x is negative. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


8-190 Math Library 60486513 H 


XTOX 


Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 0 
Upon entry, the routine calls ALOG to compute log(x), and EXP to compute 
exp(y*log(x)). 
Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 
x is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 
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Error Analysis 


The function XTOX was tested. Groups of 2,000 arguments were chosen randomly from 
given intervals. Statistics on relative error were observed. Table 8-27 shows a summary 


of these statistics. 


Table 8-27. Relative Error of XTOX 


Test Interval From 
x interval 

x*#y against x**2**(y/2) .1000E-01 
y interval 

-.6167E +03 

x**2**1.5 against .1000K +01 
xr t2*x .5000E +00 
x**1.0 against x .5000E + 00 


Effect of Argument Error 


Interval To 


.1000E + 02 


.6167E + 03 


8053+ 411 
.1000E+01 


.1000E+01 


Maximum 


3547E-12 


.1360E-13 
.1360E-13 


.6802E-14 


Root Mean 
Square 


.6352E-13 


.5687E-14 
ST15E-14 


.3442E-14 


If a small error e(b) occurs in the base b, and a small error e(p) occurs in the 
exponent p, the error in the result r is given approximately by: 


r*(jog(b)*e**p + p*(e(b))/b) 
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Example of XTOX Called From FORTRAN 


Source Code: 


PROGRAM XTOX_EXAMPLE 


Cc 

REAL x, y, XTOX 
x=2.0 
y=10.0 
PRINT *, “The XTOX of x and y is:’ 
PRINT *, XTOX(x,y) 
END 

Output: 


The XTOX of x and y is: 
1024. 
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XTOZ 


XTOZ performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. XTOZ also accepts compiler-generated calls (for example, the FORTRAN and 


Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RXTOZ and XTOZ, and the call-by-value 
entry point is MLP$VXTOZ, 


The XTOZ vector math function is divided into three routines having three separate 
entry points defined as follows: 


XTOZ(scalar,vector ) 
XTOZ(vector ,scalar) 
XTOZ(vector , vector ) 


MLP$XTOZV 
MLP$XVTOZ 
MLP$XVTOZV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a real quantity, y is a complex quantity, and x**y is a valid quantity. If x is zero, the 
real part of y must be greater than zero, and the imaginary part must be equal to 


zero. The output range is included in the set of valid complex quantities. 


Call-By-Reference Routine 


The argument pair (x,y) is checked upon entry. It is invalid if: 


x is indefinite. 
y is indefinite. 
x is infinite. 


y is infinite. 


x is equal to zero, and the real part of y is less than or equal to zero, or the 


imaginary part of y does not equal zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 

returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 


to the calling program. 


Call-By-Value Routine 


Upon entry, the real argument x is converted to complex, and the routine calls ZTOZ 


to compute the result. 
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Vector Routine 


The argument pair (x,y) is checked upon entry. It is invalid if: 


x is indefinite. 


y is indefinite. 


x is infinite. 


y is infinite. 


x is equal to zero and y is less than or equal to zero. 


x is negative. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


A group of 10,000 arguments was chosen randomly from the interval 


([-1.0,1.0] [-1.0,1.0]) and ([-1.0,1.0],[-1.0,1.0]). The maximum relative error of these 


arguments was found to be 1.7431E-11. 


Effect of Argument Error 


XTOZ 


If a small error e(x) occurs in the base x, and a small error e(z) (e(x) + i*e(y)) occurs 


in the exponent z, the error in the result w is given approximately by: 


w*(log(x)* e(z) + z*e(x)/x) 


Example of XTOZ Called From FORTRAN 


Source Code: 


PROGRAM XTOZ_EXAMPLE 


C 
REAL x 
COMPLEX zeta, omega, xtoz 
x = 5.0 
zeta = (5.0, 0) 
omega = XTOZ (x, zeta) 
PRINT *, “The XTOZ of x and zeta is:’ 
PRINT *, omega 
END 
Output: 
The XTOZ of xX and zeta is: 
(3125.,0.) 
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ZTOD 


ZTOD performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. ZTOD also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RZTOD and ZTOD, and the call-by-value 
entry point is MLP$VZTOD. 


The ZTOD vector math function is divided into three routines having three separate 
entry points defined as follows: 


ZTOD(scalar,vector) = MLP$ZTODV 
ZTOD(vector,scalar) = MLP$ZVTOD 
ZTOD(vector,vector) = MLP$ZVTODV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a complex quantity, y is a double precision quantity, and x**y is a valid quantity. If 
the real and imaginary parts of x are equal to zero, then y must be greater than zero. 
The output range is included in the set of valid complex quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
xX is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 


Upon entry, the double precision argument y is converted to complex, and the routine 
calls ZTOZ to compute the result. 


8-196 Math Library 60486513 H 


ZTOD 


Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


A group of 10,000 arguments was chosen randomly from the interval 
((-1.0,1.0],[-1.0,1.0]) and ((-1.0,1.0],[-1.0,1.0]). The maximum relative error of these 
arguments was found to be 1.7431E-11. 


Effect of Argument Error 


If a small error e(z) occurs in the base z and a small error e(e) occurs in the exponent 
e, the error in the result w is given approximately by: 


w*(e(e)*log(z) + ete(z)/z) 
Example of ZTOD Called From FORTRAN 


Source Code: 


PROGRAM ZTOD_EXAMPLE 


COMPLEX zeta, omega, ztod 

DOUBLE PRECISION y 

zeta = (5.0, -1) 

y=140.0d0 

omega = ZTOD(zeta,y) 

PRINT *, “The ZTOD of zeta and y is:’ 
PRINT *, omega 

END 


Output: 


The ZTOD of zeta and y is: 
(-8.9680485084 14E+98 , -6 .6625567 18066E+98) 
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ZTOI performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. ZTOI also accepts compiler-generated calls (for example, the FORTRAN and Ada 
compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RZTOI and ZTOI, and the call-by-value 
entry point is MLP$VZTOI. 


The ZTOI vector math function is divided into three routines having three separate 
entry points defined as follows: : 


ZTOI(scalar,vector) = MLP$ZTOIV 
ZTOI(vector,scalar) = MLP$ZVTOI 
ZTOI(vector,vector) = MLP$ZVTOIV 


The input domain for this function is the collection of all valid pairs (x,y), where x is 
a complex quantity, y is a integer quantity, and x**y is a valid quantity. If the real 
and imaginary parts of x are equal to zero, then y must be greater than zero. The 
output range is included in the set of valid complex quantities. 
Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 

x is indefinite. 

x is infinite. 


x is equal to zero and y is less than or equal to zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 
it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 


Let x represent the base and y represent the exponent. If y has binary representation 
000... .000i(n)i(n-1) ...i(1)i(0), where each i(j)(0 = j = n) is 0 or 1, then: 


y = i1(0)*2**0 + 1(1)*#2**1 + 1... + i(n)*2**n 
n (log(2)y) = greatest integer not exceeding log(2)y 


Then: 


x**y = prod[x**2**j : 0 < j <n and i(j) = 1] 
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The numbers x**0, x = x**2**0, x**2, x**4, ..., x**(2)**n are generated during the 
computation by successive squarings, and the coefficients i(0), ...., i(n) are obtained as 
sign bits of successive circular right shifts of y within the computer. A running product 
is formed during the computation so that smaller powers of x can be discarded. The 
computation then becomes an iteration of the algorithm: 


x**y = 1, if y = 0 and x is not= 0 
= (x*x)**(y/2), if y > 0 and y is even 
= (x*x)**((y-1)/2)*x, if y > 0 and y is odd 


Upon entry, if the exponent y is negative, y is replaced by -y and a sign flag is set. 
x**y is computed according to this algorithm, and if the sign flag was set, the result is 
reciprocated before being returned to the calling program. 


Vector Routine 

The argument pair (x,y) is checked upon entry. It is invalid if: 
xX is indefinite. 
x is infinite. 
x is equal to zero and y is less than or equal to zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Effect of Argument Error 


If a small error e occurs in the base b, the error in the result will be given 
approximately by n*b**(n-1)*e, where n is the exponent given to the routine. 


Example of ZTOI Called From FORTRAN 


Source Code: 


PROGRAM ZTOI_EXAMPLE 


C 

INTEGER i 
COMPLEX zeta, omega, ztoi 
ji = 12 
zeta = (2.0, -1) 
omega= ZTOI (zeta,i) 
PRINT *, “The ZTOI of zeta and i is:’ 
PRINT *, omega 
END 

Output: 


The ZTOI of zeta and i is: 
(11753. , 10296. ) 
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ZTOX performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. ZTOX also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points are MLP$RZTOX and ZTOX, and the call-by-value 
entry point is MLP$VZTOX. 


The ZTOX vector math function is divided into three routines having three separate 
entry points defined as follows: 


ZTOX(scalar,vector) = MLP$ZTOXV 
ZTOX(vector,scalar) = MLP$ZVTOX 
ZTOX(vector,vector) = MLP$ZVTOXV 


The input domain for this function is the collection of all valid argument pairs (x,y), 
where x is a complex quantity, y is a real quantity, and x**y is a valid quantity. If 
the real and imaginary parts of x are equal to zero, then y must be greater than zero. 
The output range is included in the set of valid complex quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 

x is indefinite. 

y is indefinite. 

x is infinite. 

y is infinite. 

x is equal to zero and y is less than or equal to zero. 
If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 


it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 


Upon entry, the real argument is converted to a complex argument, and the routine 
calls ZTOZ to compute the result. 
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Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


A group of 10,000 arguments was chosen randomly from the interval 
([-1.0,1.0] ,[-1.0,1.0]) and ({-1.0,1.0],[-1.0,1.0]). The maximum relative error of these 
arguments was found to be 1.7431E-11. 


Effect of Argument Error 


If a small error e(z1) occurs in the base zl and a smal! error e(z2) occurs in the 
exponent z2, the error in the result w is given approximately by: 


w*(e(z2)*log(z1) + 22*e(21)/z21) 


Example of ZTOX Called From FORTRAN 


Source Code: 


PROGRAM ZTOX_EXAMPLE 


C 

REAL x 
COMPLEX zeta, omega, ztox 
x = 12.0 
zeta = (2.0, -1) 
omega= ZTOX (zeta,x) 
PRINT *, “The ZTOX of zeta and x is:’ 
PRINT *, ZTOX (zeta,x) 
PRINT *, omega 
END 

Output: 


The ZTOX of zeta and x is: 
(11753. , 10296. ) 
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ZTOZ performs exponentiation for program statements that raise integer quantities to 
real exponents. It accepts an integer argument and a real argument and returns a real 
result. ZTOZ also accepts compiler-generated calls (for example, the FORTRAN and 
Ada compilers provide the exponentiation operator **). 


The call-by-reference entry points-are MLP$RZTOZ and ZTOZ, and the call-by-value 
entry point is MLP$VZTOZ. 


The ZTOZ vector math function is divided into three routines having three separate 
entry points defined as follows: 


ZTOZ(scalar,vector) = MLP$ZTOZV 
ZTOZ(vector,scalar) = MLP$ZVTOZ 
ZTOZ(vector,vector) = MLP$ZVTOZV 


The input domain is the collection of all valid complex pairs (x,y). If the real and 
imaginary parts of x are equal to zero, then the real part of y must be greater than 
zero, and the imaginary part must be equal to zero. The output range is included in 
the set of valid complex quantities. 


Call-By-Reference Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 


x is equal to zero, and the real part of y is less than or equal to zero, and the 
imaginary part of y does not equal zero. 


If the argument pair is invalid, a diagnostic message is displayed. If the argument pair 
is valid, the call-by-value routine is called, and the result of the computation is 
returned to the call-by-reference routine. The result is checked. If the result is infinite, 


it is invalid, and a diagnostic message is displayed. If the result is valid, it is returned 
to the calling program. 


Call-By-Value Routine 
The formula used for computation is: 
x**y = exp(y*log(x)), where x > 0. 


Upon entry, argument checking is performed. If the arguments are valid, the routine 
calls CLOG to compute log(x), and CEXP to compute exp(y*log(x)). 


8-202 Math Library , 60486513 H 


ZTOZ 


Vector Routine 
The argument pair (x,y) is checked upon entry. It is invalid if: 
x is indefinite. 
y is indefinite. 
x is infinite. 
y is infinite. 
x is equal to zero and y is less than or equal to zero. 


See Vector Error Handling in chapter 7, Vector Processing, for further information. 


Error Analysis 


A group of 10,000 arguments was chosen randomly from the interval 
([-1.0,1.0],[—1.0,1.0]) and ({[-1.0,1.0],[-1.0,1.0]). The maximum relative error of these 
arguments was found to be 1.7431E-11. 


Effect of Argument Error 


If a small error e(z1) occurs in the base zl and a small error e(z2) occurs in the 
exponent z2, the error in the result w is given approximately by: 


w*(e(z2)*1log(z1) + 22*e(z1)/21) 
Example of ZTOZ Called From FORTRAN 


Source Code: 


PROGRAM ZTOZ_EXAMPLE 


C 

COMPLEX alpha, zeta, omega, ztoz 
alpha = (12.0, 0) 
zeta = (2.0, -1) 
omega= ZTOZ (alpha, zeta) 
PRINT *, “The ZTOZ of alpha and zeta is:’ 
PRINT *, omega 
END 

Output: 


The ZTOZ of alpha and zeta is: 
(-114.0508449541, -87 .91134605528) 
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Auxiliary Routines | a: 


The auxiliary routines cannot be called by their Math Library names. As the following 
list indicates, these routines are algorithmic modules that are called by Math Library 
functions: 


e ACOSIN (called by ACOS and ASIN) 

@ COSSIN (called by CSIN and CCOS) 

e DASNCS (called by DCOS and DSIN) 

@ DEULER (called by DEXP and DTANH) 

@ DSNCOS (called by DCOS and DSIN) 

e HYPERB (called by COSH and SINH) 

@ SINCOS (called by SIN and COS) 

® SINCSD (called by SIND and COSD) 

Most of these routines can be called by their call-by-value entry points from assembler 


programs, but this is not recommended. These routines are described in this manual 
for algorithmic and error analysis. 
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ACOSIN 


ACOSIN is an auxiliary routine that computes the inverse sine or inverse cosine 
function. It accepts a real argument and returns a real result. 


There are no call-by-reference entry points for ACOSIN. The call-by-value entry points 
are MLP$VACOS and MLP$VASIN. 


The input domain is the collection of all valid real quantities in the interval [-1.0,1.0]. 
The output range is included in the set of valid, nonnegative real quantities less than 


or equal to pi. 


Call-By-Value Routine 


Formulas used in the computation are: 


arcsin(x) 
arcos(x) 
arcsin(x) 
where -. 
arcos(x) 
arcsin(x) 
arcos(x) 
arcsin(1) 
arcos(1) 


nooo t 


where: 


w 
z 
ITER(y,n) = 


The constants used are: 


= 3.173 
= 1.160 
= 50.319 
-2.369 
-226 
-35 .629 

= 37.459 
= 349.319 
= .746 


nw Kerem OO 3 0 3 
ul 
[eo] 


170 
394 
055 
588 
467 
481 
230 
357 
926 


078 
629 
960 
855 
970 
597 
925 
025 
199 


The approximation of arcsin 
varying r,e,m,...,S. 
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-arcsin(-x), x <= 5 

pi - arcos(-x), x < -.5 

xX + x**3*s*((w + 2 - j)*wt+a+t+m/(e - x**2)), 
<x< .5 

pi/2 - arcsin(x), -.5 <x < .5 

pi/2 - arcos(x), 5 <x < 1.0 
arcos(1-ITER((1 - x),n))/2**n, .5 < x < 1.0 
pi/2 


(x**2 - c)*z + k 
(x**2 + p)x**2 + j 
n iterations of y = 4*y - 2*y**2 


419*10**-3 


(—.5,.5) is an economized approximation obtained by 


60486513 H 


ACOSIN 


The algorithm used is: 


a. If ACOS entry, go to step g. 
b. If |x | > .5, go to step h. 
= 0 (Loop counter). 


= 0, if ASIN entry. 


n 
q 
y = x*#2 
u 
u = pi/2, if ACOS entry. 


ul 


(y + r)ty + i 

(y - c)*¥z2 +k 

q + s*qty*((w + 2 - j)*w + a+t+m/(e - y)) 
u- p 

p/2**n 


<UUDEN 
" 


_ 
" 


e. If ASIN entry, go to step k. 


f. If x is in (-.5,1.0), return. 
XF = 2*u - (Y1) 
Return. 


g. If |x | < .5, go to step c. 


h. If x = 1.0 or -1.0, go to step 1. 
If x is invalid, go to step m. 
n = 0 (Loop counter). 
y = 1.0 - [xl], and normalize y. 


i. NW = 4%y — 2*y**2 
n=nt 1.0 
If 2*y < 2 - sqrt(3) = .267949192431, y = h, and go to step i. 


j. qz=1.0- h, and normalize gq. 
y = gr*2 
u = pi/2 
Go to step d. 


k. Y1=u- (Y¥1), and normalize Y1. 
Affix sign of x to Y1 = XF. 
Return. 


1. XF = pi/2, if x = 1.0. 
XF = -pi/2, if x = -1.0. 
If ASIN entry, return. 
XF = 0, if x = 1.0. 
XF = pi, if x = -1.0. 
Return. 


m. Return. 
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Error Analysis 


See the descriptions of functions ACOS and ASIN. 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e/(1.0 -— x**2)**.5. 
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COSSIN 


COSSIN is an auxiliary routine that accepts calls from other math functions that 
require simultaneous computation of the sine and cosine of the same argument. 
COSSIN accepts a real argument and returns two real results. 


See the descriptions of functions CSIN and CCOS for additional information. 


Call-By-Value Routine 


The argument is reduced to the interval [-pi/4,pi/4]. Polynomials p(x) and q(x) of 
degrees 11 and 12 are used to compute sin(x) and cos(x) over that interval. Upon 
entry, the argument x is multiplied by 2/pi. Then, the nearest integer n to 2/pi*x is 
computed. The upper and lower halves of the result are added. The value of y is in the 
interval (-pi/4,pi/4). y = x -— n*pi/2 is computed in double precision as the reduced 
argument for input to p(y) and q(y). Then sin(x) and cos(x) are computed from these as 
indicated by the value k = mod(n,4), where k = 0, 1, 2, 3. The formula used to 
compute sine(x) is: 


sin(x) = sin(y + n*p/2) = sin(y + k*pi/2) 
= sin(y)*cos*(k*pi/2) + cos(y)*sin(k*pi/2) 


A similar formula is used for the computation of cosine(x). Depending upon k, either 
the sine(k = 0,1) or cosine(k = 2,3) of y is evaluated and complemented, if necessary. 


The polynomials p(x) and q(x) are: 


p(x) = s(O0)x + s(1) x**3 + s(2)x**5 + s(3)x**7 + s(4)x**9 + 
s(5)x**11 


a(x) = c(0) + c(1)x**2 + c(2)x**4 + c(3)x**6 + c(4)x**8 + 
c(5)x**10 + c(6)x**12 


where the coefficients are: 


s(0) = .999 999 999 999 972 

s(1) = -.166 666 666 665 404 

s(2) = .833 333 331 696 029*10**-2 
s(3) = -.198 426 073 537 90*10**-3 
s(4) = .275 548 564 509 884*10**-5 
s(5) = -.247 320 720 952 463*10**-7 
c(0) = .999 999 999 999 996 

c(1) = -.499 999 999 999 991 

c(2) = .041 666 666 666 470 5 

c(3) = -.138 888 888 888 159*10**-2 
c(4) = .248 015 784 673 257*10**-4 
c(5) = -.275 552 187 277 097*10**-6 
c(6) = .206 291 063 476 645*10**-8 
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COSSIN 


The coefficients were obtained as follows. The polynomials of degrees 15 and 14, 
obtained by truncating the Maclaurin series! for sin(x) and cos(x), were telescoped to 
form the polynomials p(x) and q(x) of degrees 11 and 12. The telescoping is done by 
removing the leading term of the polynomial. This is accomplished by subtracting an 
appropriate multiple of T(n)(a(x - x(0))) of the same degree n; 2/a is the length of the 
interval of approximation, and x(0) is its center. 


The Chebyshev polynomial of degree n, T(n)(x), is defined by T(n)(x) = 
cos(n*arccos(x)).“ The absolute value of x is no greater than one and satisfies the 
recurrence relation: . 


T(O)(x) = 1 
T(1)(x) = x 
T(n + 1)(x) = 


2xT(n)(x) - T(n - 1)(x) 
where n = 1. 


For n = 1.0, T(n)(x) is the unique polynomial 2(n - 1.0)*x**n + ... of degree n whose 
maximum absolute value over the interval [-1.0,1.0] is minimal. This maximum 
absolute value is one. 


The formulas used for the range reduction are: 
sin(x) = (-1)**n*sin(y) 
cos(x) = (-1)**n*cos(y) 
if x = y + n*pi, n an integer 
sin(x) = cos(x - pi/2) 
cos(x) = -sin(x - pi/2) 
if pi/4 < x < pi/2 
Error Analysis 


The maximum absolute error in the approximation of sin(x) by p(x) in the interval 
(—pi/4,pi/4) is .1893E-14. The maximum absolute error in the approximation of cos(x) 
by q(x) is .3687E-14. 


Effect of Argument Error 


Not applicable, since this routine is not called directly by the user’s program. 


1, For a discussion of Maclaurin series, refer to any calculus text (for example, Calculus and Analytic 
Geometry by G. B. Thomas). 


2. For a discussion of the Chebyshev polynomial, see any analysis text (for example, Introduction to 
Numerical Analysis by F. B. Hildebrand). 
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DASNCS 


DASNCS is an auxiliary routine that computes the inverse sine or inverse cosine 
function. It accepts a double precision argument and returns a double precision result. 


There are no call-by-reference entry points for DASNCS. The call-by-value entry points 
are MLP$VDACOS and MLP$VDASIN. 


The input domain is the collection of all valid double precision quantities in the 
interval [-1.0,1.0]. The output range at entry point MLP$VDACOS is included in the 
set of valid, nonnegative double precision quantities less than or equal to pi. The 
output range at entry point MLP$VDASIN is included in the set of valid double - 
precision quantities in the interval [—pi/2,pi/2]. 


Call-By-Value Routine 
The following identities are used to move the interval of approximation to [0,sqrt(.5): 


arcsin(-x) = -arcsin(x) 


arccos(x) = pi/2-arcsin(x) 
arcsin(x) = arccos(sqrt(1.0 - x**2)), if x > 0 
arccos(x) = arcsin(saqrt(1.0 - x**2)), if x > 0 


The reduced value is called y. If y = .09375, no further reduction is performed. If not, 
the closest entry to y in a table of values (z,arcsin(z),sqrt(1.0 -— z**2), z = .14, .39, .52, 
.64) is found, and the formula used is: 


arcsin(x) = arcsin(z) + arcsin(w) 


where w = x*sqrt(1.0 — z**2) — z*sqrt(1.0 - x**2). The value of w is in the open 
interval (-.0792,.0848). 


The arcsin of the reduced argument is then found using a 15th order odd polynomial 
with quotient: 


x + x**3(c(3) + x**2(c(5) + x**2(c(7) + x**2(c(11) + x**2(c(13) + 
x**2(c(15) + a/(b-x**2))))))) 


where all constants and arithmetic operations before c(11) are double precision and the 
rest are single precision. The addition of c(11) has the form single+single=double. The 
polynomial is derived from a minimax rational form (denominator is (b — x**2)) for 
which the critical points have been perturbed slightly to make c(11) fit in one word. 


To this value, arcsin(z) is added from a table if the last reduction above was done and 
the sum is conditionally negated. Then 0, —pi/2, +pi/2, or pi is added to complete the 
unfolding. 


Error Analysis 


See the descriptions of functions DACOS and DASIN. 


Effect of Argument Error 
See the descriptions of functions DACOS and DASIN. 
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DEULER 


DEULER 


DEULER is an auxiliary routine that accepts calls from other math functions. It 


performs computations that are common among these routines. 


The input and output ranges are described in the DEXP and DTANH function 


descriptions. 


Call-By-Value Routine 


Constants used in the algorithm are: 


log(2) (in double precision) 


1.0/10g(2) 

d3 = - 166 
d5 = . 833 
dq7 = . 198 
d9 = .275 
pe = -.474 
pa = .566 
pb = 272.110 
c11 = .250 


666 
333 
412 
573 
970 
228 
632 
521 


666 
333 
698 
192 
880 
284 
903 
083 


666 
333 
412 
239 
178 
957 
710 
854 


666 666 666 666 666 709 

333 333 333 331 234 953*10**-2 
698 412 700 466 386 658*10**-3 
858 897 408 325 908 796*10**-5 
988* 10**-10 

811*10**-7 


439* 10**-7 


Arithmetic operations with d subscripts are done in double precision, and operations 
with u subscripts are done in single precision. For example, d3 +(d) q indicates that 
the addition is in double precision. An operand with a u or | subscript denotes the first 
or second word, respectively, of the double precision pair of words containing the 


operand. 
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DEULER 


The algorithm used is: 


a. On 


nearest integer to x/log(2), 


y = x - n*log(2), 
Then y is in [-1/2*10g(2), 1/2*1o0g(2)]. 


b. q 
c. Dp 
d. s 


(y) (u) *(u) Cy) (u) 


a*(d)(d3 +(d) q*(d)(d5 +(d) q*(d)(d7 +(d) g*(d)(d9 +(d) 
a*(d)(c11 +(d) q*(d)(pa/(pb - q) + pc)))))) 


(y)(u) + (d)(y)(u)*(d)p 


e. Compute hm = saqrt(1.0 + s**2). 


hi 
hj 
hk 
hl 
hm 


3*q + ((s)(u))**2 computed in single precision. 
hi + hi 

2*(1.0 + hj) 

((y)(u)*(u) (y)(u) - hj)/nk - hi 

hj + (u)(hk - (u)h1)*(u)(h1/hk) 

(hm now carries cosh-1.0 in single precision. ) 


s+ (A)(((y)(1) + (r)(y) (1) *(u)hm) + (r)((s)(1) + 
(r)((y)(u)* (1) (p)(u) + (r)(y)(u)*(r)(p)1)))) 


(DS now contains sinh(y) in double precision.) 


g. DC = hm + (d)(DS*DS - 2*hm - hm*hm)/(2(1.0 + hm)) computed ‘in double 
precision. 


h. DX = DS + DC 


i. Clean up DS, DC, DX with (X7) =n. 


Register pair XA-XB = DS = sinh(y). 
Register pair X8-X9 = DC = cosh(y) - 1.0. 
Register pair X4-X5 = DX = exp(y). 


j. Return. 


Error Analysis 


See the descriptions of functions DEXP and DTANH. 


Effect of Argument Error 


See the descriptions of functions DEXP and DTANH. 
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DSNCOS 


DSNCOS is an auxiliary routine that computes the trigonometric sine or trigonometric 
cosine function. It accepts a double peceton argument and returns a double precien 
result. 


There are no call-by-reference entry points for DSNCOS. The call-by-value entry points 
are MLP$VDCOS and MLP$VDSIN. 


The input domain for this routine is the collection of all valid double precision 
quantities whose absolute value is less than 2**47. The output range is included in the 
set of valid double precision quantities in the interval [-1.0,1.0]. 


Call-By-Value Routine 


Upon entry, the argument x is made positive and is multiplied by 2/pi in double 
precision, and the nearest integer n to x*2/pi is computed. At this stage, x*2/pi is 
checked to see that it does not exceed 2**47. If it does, a diagnostic message is 
returned. Otherwise, y = x — n*pi/2 is computed in double precision as the reduced 
argument, and y is in the interval [-pi/4,pi/4]. The value of mod(n,4),.the entry point 
called, and the original sign of x determine whether a sine polynomial approximation 
“ p(x) or a cosine polynomial approximation q(x) is to be used, A flag is set to indicate 
the sign of the final result. et 


For x in the interval [-pi/4,pi/4], the sine polynomial approximation is: 


p(x) = a(1)x + a(3)x**3 + a(5)x#*5 + a(7)x**7 + a(9)x**9 + a(di)xe*11 + 
a(13)x**13** + a(15)x**15 + a(17)x**17 + a(19)x**19 + a(21)x**21_ 


and the cosine polynomial approximation is: 


a(x) = b(O) + b(2)x**2 + b(4)x**4 + b(6)x**6 + b(8)x**8 + b(10)x**10 + 
b(12)x**12 + b(14)x**14 + b(16)x**16 + b(18)x**18 + b(20)x**20— 
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The coefficients are: 


a(1) 
a(3) 
a(5) 
a(7) 
a(9) 
a(11) 
a(13) 
a(15) 


a(17) = 
a(19) = 


a(21) 
b(0) 
b(2) 
b(4) 
b(6) 
b(8) 
b(10) 
b(12) 


b(14) = 
b(16) = 
b(18) = 


b(20) 


.999 
. 166 
.833 
. 198 
.275 
.250 
. 160 
. 764 
.281 
.822 
. 194 
.999 
.499 
-416 
. 138 
248 
275 
.208 
.114 
-477 
. 156 
-408 


999 
666 
333 
412 
573 
521 
590 
716 
145 
042 
362 
999 
999 
666 
888 
015 
573 
767 
707 
947 
187 
023 


999 
666 
333 
698 
192 
083 
438 
373 
706 
461 
013 
999 
999 
666 
888 
873 
192 
569 
455 
696 
668 
947 


999 
666 
333 
412 
239 
854 
368 
079 
930 
317 
130 
999 
999 
666 
888 
015 
239 
878 
958 
822 
345 
777 


999 
666 
333 
698 
858 
417 
179 
886 


999 
666 
333 
412 
906 
101 
417 
084 


999 
666 
333 
698 
394 
138 
271 
755 


018*10**-14 
923* 10**-17 
224*10**-19 


999 
999 
666 
888 
873 
858 
619 
584 
393 


999 
999 
666 
888 
015 
775 
214 
315 
115 


999 
999 
666 
888 
699 
558 
898 
495 
933 


316* 10**-15 
860* 10**-18 


999 
666 
332 
291 
406 
076 
194 
348 


999 
999 
666 
755 
922 
669 
747 
950 
106 


999 
666 
709 
344 
844 
473 
064 
748 


999 
999 
139 
436 
737 
957 
461 
765 
267 


99 

52 . 
57*10**=2 
78* 10**-3 
01*10**-5 
5*10**-7 
61*10**-9 
91*10**-12 


02 

28*10**=2 
30* 10**-4 
11*10**-6 
35* 10**-8 
75*10**-10 
21* 10**-13 


DSNCOS 


These polynomials are evaluated from right to left in double precision. The sign flag is 
used to give the result the correct sign before returning to the calling program. 


Error Analysis 


See the descriptions of functions DCOS and DSIN. 


Effect of Argument Error 


See the descriptions of functions DCOS and DSIN. 
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HYPERB 


HYPERB is an auxiliary routine that accepts calls from other math functions that 
require the simultaneous hyperbolic sine and hyperbolic cosine of the same argument. 
HYPERB accepts a real argument and returns two real results. 


The entry points and input and output ranges for this routine are described in in the 
CSIN and CCOS function descriptions. 


Call-By-Value Routine 


Upon entry, the routine computes e**x = exp(x), where x is the angle passed to 
HYPERB. The hyperbolic cosine is computed by: 


cosh(x) = 0.5*(exp(x) + exp(-x)) 
If |x| = .22, the hyperbolic sine is computed by: 
sinh(x) = 0.5*(exp(x) - exp(-x)) 


For |x| < 0.22, the Maclaurin series® for sinh is truncated after the term x**9/9! and 
the resulting polynomial is taken as the approximation: 


sinn(x) = x + x*®*3/3! + x*®**5/5! + x**7/7! + x**9/Q9! 


Error Analysis 


See the descriptions of functions COSH and SINH. 


Effect of Argument Error 


See the descriptions of functions COSH and SINH. 


\ 


3. For a discussion of Maclaurin series, refer to any calculus text (for example, Calculus and Analytic 
Geometry by G. B. Thomas). 
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SINCOS 


SINCOS is an auxiliary routine that computes the trigonometric sine and cosine 
functions. It accepts a real argument and returns a real result. 


There are no call-by-reference entry points for SINCOS. The call-by-value entry points 
are MLP$VCOS and MLP$VSIN. 


The input domain for this routine is the collection of all valid real quantities whose 
absolute value is less than 2**47. The output range is included in the set of valid real 
quantities in the interval [-1.0,1.0]. 


Call-By-Value Routine 


If x is valid, then COS(x) or SIN(x) is calculated by using the periodic properties of the 
cosine and sine functions to reduce the task to finding a cosine or sine of an 
equivalent angle y within [-pi/4, pi/4] as follows: 


If N + K is even 
then 
Z 
else 
_Z = cos(y) 
If MOD(N + K, 4) is 0 or 1 (that is, the second last bit of N + K is even) 
then 
S=0 
else 
Ss 


sin(y) 


mask(1) 


where K is 0, 1, or 2 according to whether the SIN of a positive angle, the COS of 
any angle, or the SIN of a negative angle is to be calculated. N is the nearest integer 
to 2/pi*x, and y is the nearest single precision floating-point number to x — n*pi/2. The 
argument x is the absolute value of the angle. The desired SIN or COS is xor(S, Z). 


Once the angle has been reduced to the range [-pi/4, pi/4], the following 
approximations are used to calculate either the cosine or the sine of the angle, 
providing 48 bits of precision. 


If the cosine or the angle is required, the approximation used is 
cosine(y) = 1 - y*y*P(y*y) 

where y is the angle and P(w) is the quintic polynomial: 
P(w) = PO + P1*w + P2*w**2 +P3 + w**3 + P4*wt*4 + P5*w**5 


such that P(y*y) is a minimax polynomial approximation to the function (1 - 
cos(y))/y**2. 


The coefficients are: 


P5 = -2.070062305624629462E-9 
P4 = 2.755636997406588778E-7 
P3 = -2.48015852 120642667 1E-5 
P2 = 1.388888888727866775E-3 
P1 = -4.166666666666468 1 16E-2 
PO = 5.000000000000000000E-1 
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If the sine of the angle is required, the approximation used is 
sine(y) = y - yty*y*Q(y*y) 

where y is the angle and Q(w) is the quintic polynomial: 
Q(w) = QO + Q1*w + Q2*w**2 +Q3*w**3 + Q4*w**4 + Q5*w*t5 


such that Q(y*y) is a minimax polynomial approximation to the function (y - 
sin(y))/y**3. . 


The coefficients are: 


Q5 = -1.591814257033005283E- 10 
Q4 = 2.505113204973767698E-8 
Q3 = -2.7557316 10365754733E-6 
Q2 = 1.984126983676100911E-4 
Q1 = -8.333333333330950363E-3 
QO = 1.666666666666666463E-1 


Error Analysis 


The function SINCOS was tested against 4*COS(x/3)**3 - 3*COS(x/3). Groups of 2,000 
arguments were chosen randomly from the interval [.2199E+02,.2356E+ 02]. Statistics 
on relative error were observed: maximum relative error was .1404E-13, and root 
mean square relative error was .3245E-14. : 


Effect of Argument Error 


If a small error e occurs in the argument x, the error in the result is given 
approximately by e*cos(x) for sin(x) and —e*sin(x) for cos(x). 
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SINCSD 


SINCSD computes the sine and cosine functions for arguments in degrees. It accepts a 
real argument and returns a real result. 


There are no call-by-reference entry points for SINCSD. The call- Pee entry points 
are MLP$VCOSD and MLP$VSIND. 


The input domain for this routine is the collection of all valid real quantities whose 
absolute value is less than 2**47. The output range is included in the set of valid real 
quantities in the interval [-1.0,1.0]. 


Call-By-Value Routine 


The result is put in the interval [-45,45] by finding the nearest integer, n, to x/90, and 
subtracting n*90 from the argument. The reduced argument is then multiplied by 
pi/180. The appropriate sign is copied to the value of the appropriate function, sine or 
cosine, as determined by these identities: 


sin(x + 360 degrees) = sin(x) 
sin(x + 180 degrees) = -sin(x) 
sin(x + 90 degrees) = cos(x) 
sin(x - 90 degrees) = -cos(x) 
cos(x + 360 degrees) = cos(x) 
cos(x + 180 degrees) = -cos(x) 
cos(x + 90 degrees) = -sin(x) 
cos(x - 90 degrees) = sin(x) 


Error Analysis 


The reduction to (-45,+ 45) is exact; the constant pi/180 has relative error 1.37E-15, 
and multiplication by this constant has a relative error 5.33E-15, and a total error of 
6.7E-15. Since errors in the argument of SIN and COS contribute only pi/4 of their 
value to the result, the error due to the reduction and conversion is, at most, 5.26E-15 
plus the maximum error in SINCOS over (-pi/4,+ pi/4). 


A group of 10,000 arguments was chosen at random from the interval [0,360]. The 
maximum relative error of these arguments was found to be .7105E-14 for COSD and 
.1403E-13 for SIND. 


Effect of Argument Error 


Errors in the argument x are amplified by x/tan(x) for SIND and x*tan(x) for COSD. 
These functions have a maximum value of pi/4 in the interval (-45,+45) but have 
poles at even (SIND) or odd (COSD) multiples of 90 degrees, and are large between 
multiples of 90 degrees if x is large. 
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Algorithm Error Dummy Argument 


Glossary | A 


A 


Algorithm Error 

Error caused by inaccuracies inherent in the mathematical process used to compute the 
result. It includes error in coefficients used in the algorithm. 

Argument 

A variable cr constant that is passed to a routine and used by that routine to compute 
a function. The actual value of the variable is passed when a routine is called by 
value; the address of the variable is passed when the routine is called by reference. 
Argument Set 

An ordered list of one or more arguments. 

Auxiliary Routine 


A math routine which is not directly called from program code, but assists in the 
computation of a Math Library function. 


‘C 


Call-by-Address 


See call-by-reference. 


Call-by-Reference 

A method of referencing a subprogram in which the addresses of the arguments are 
passed. Synonymous with call-by-address. 

Call-by-Value 


A method of referencing a subprogram in which the values of the arguments are 
passed. 


D 
Data Descriptor 


Describes data by pointing to one or more contiguous data locations. 


Domain 

The collection of argument lists for which an entry point (function call) has been 
designed to return meaningful results without generating an error condition. 
Dummy Argument 


A variable or constant that is passed to a routine, but is not used by the routine to 
compute a function. 
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E 


Entry Point 

A statement within a math routine at which execution can begin. There may be more 
than one entry point into a math routine. 

Error 


The computed value of a function minus the true value. 


Exponentiation Routine . 

A math routine which accepts compiler-generated calls from a source program to 
perform exponentiation. These calls are generated when a program statement involves 
exponentiation of certain number types. Exponentiation routines are not called directly 
using their function names. 

External Routine 


A predefined subprogram that accepts calls from program code to compute certain 
mathematical functions. 


F 


Function Name 


A symbolic name that appears in a program and causes a math routine to be executed 
(for example, ABS). 


Indefinite Value 

A value that results from a mathematical operation that cannot be resolved, such as a 
division where the dividend and divisor are both zero. Indefinite numbers are 
nonstandard floating-point numbers with exponents in the range of 7000 hexadecimal to 
7FFF hexadecimal or F000 hexadecimal to FFFF hexadecimal. 

Infinite Value 

A value that results from a computation whose result exceeds the capacity of the 
computer. 

Input Range 

A collection of argument sets for which a given math routine will return a valid result. 


Intrinsic Function 


A compiler-defined FORTRAN procedure that returns a single value. 


M 


Machine Round-Off Error 


Machine round-off error is caused by the finite nature of the computer. Because only a 
finite number of bits can be represented in each word of memory, some precision is 
lost. 
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N 


Number Types 


A classification of the numbers processed by the math routines. The math routines 
perform computations on four number types: integer, single precision floating-point, 
double precision floating-point, and complex floating-point. 


O 


Output Range 


The collection of results obtained by using the arguments in the input domain of each 
math routine for computation of the function or routine. . 


Q 


Quintic 
An algebraic function of the fifth degree. A quintic polynomial is a polynomial equation 
of the fifth degree. : 


R 


Range 

The collection of results obtained by entering members of the domain into an entry 
point. 

Relative Error 

The error of a function divided by the true value. The maximum relative error 
approximates the worst-case behavior of the function in the given interval. 

Root Mean Square Relative Error 

The square root of the average of the squares of the relative errors of all the 
arguments. 

Routine 


A computer subprogram that computes commonly occurring math functions and 
performs other tasks such as input and output. A method of referencing a subprogram, 
that is, either by values or by address. 


S 


Scalar 
A constant, variable, array element, or substring of any type. 


Stride 


The distance measured in terms of array elements between two consecutive elements of 
the same dimension. For the Math Library, the stride is always equal to one. 
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U 


Units in the Last Place (ulp) 


A mathematical concept used to describe the accuracy of an algorithm. 


Vv 


Vector 


One-dimensional array of up to 512 elements. 


Vectorization 


The manipulation of object code to reduce execution time taking advantage of the 
vector processing capabilities of the CYBER 180/990 Series running FORTRAN Version 
2. 
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Related Manuals 7 B 


Table B-1 lists all manuals that are referenced in this manual or that contain 
background information. A complete list of NOS/VE manuals is given in the NOS/VE 
System Usage manual. If your site has installed the online manuals, you can find an 
abstract for each NOS/VE manual in the online System Information manual. To access 
this manual, enter: 


explain 
Table B-1 also lists a few VX/VE manuals. Additional VX/VE manuals are listed in 
the VX/VE Programmer Reference Manual. 
Ordering Printed Manuals 
You can order Control Data manuals through Control Data sales offices or through: 


Control Data Corporation 
Literature and Distribution Services 
308 North Dale Street 

St. Paul, Minnesota 55103 


Accessing Online Manuals 

To access an online manual, log in to NOS/VE and specify the online manual title 
(listed in table B-1) on the EXPLAIN command. For example, to read the FORTRAN 
Version 1 Quick Reference online manual, enter: 


explain manual=fortran 
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Accessing Online Manuals 


Table B-1. Related Manuals 


Manual Title 
Ada for NOS/VE Usage 


APL for NOS/VE Usage 

BASIC for NOS/VE Usage 

C for NOS/VE Usage 

CYBIL Language Definition Usage 

Debug for NOS/VE Usage 

FORTRAN for NOS/VE LIB99 

FORTRAN Version 1 Language Definition Usage 
FORTRAN Version 1 Quick Reference 
FORTRAN Version 2 Language Definition Usage 
FORTRAN Version 2 Quick Reference 

LISP for NOS/VE Language Definition Usage 
NOS/VE Diagnostic Messages 

NOS/VE System eave: | 

Pascal for NOS/VE Usage 

Prolog for NOS/VE Usage 

VX/VE Programmer Reference Manual 

VX/VE User Guide 
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Publication Online 


Number 


60498113 
60485813 
60486313 
60469830 
60464113 
60488213 
60485915 
60485913 


L60485918 


60487113 


L60487118 


60486213 
60484613 
60464014 
60485613 
60486713 
60469820 
60469780 


Title 
ADA 


BASIC 


FORTRAN 


VFORTRAN 


MESSAGES 


PASCAL 
PROLOG 
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ASCII Character Set C 


Table C-1 gives the ASCII character set with the hexadecimal character code for each 
ASCII character. 


See the appropriate language manual as listed in appendix B for additional ASCII 
character set tables. 
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ASCII Character Set 


Table C-1. ASCII Character Set and Collating Sequence 


Collating Graphic 
Sequence ASCII Code or 
Position (Hexadecimal) Mnemonic 
0 00 NULL 
1 01 SOH 
2 02 STX 
3 03 ETX 
4 04 EOT 
5 05 ENQ 
6 06 ACK 
7 07 BEL 
8 08 BS 

9 09 HT 
10 0A LF 
11 0B VT 
12 oC FF 
13 OD CR 
14 0E sO 
15 OF SI 

16 10 DLE 
17 11 DC1 
18 12 DC2 
19 13 DC3 
20 14 DC4 
21 15 NAK 
22 16 SYN 
23 17 ETB 
24 18 CAN 
25 19 EM 
26 1A SUB 
27 1B ESC 
28 1C FS 
29 1D GS 
30 1E RS 
31 1F US 
32 20 SP 
33 21 ! 

34 22 " 

35 23 # 

36 24 $ 

37 25 % 

38 26 & 

39 27 : 
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Name or Meaning 


Null 

Start of heading 
Start of text 

End of text 

End of transmission 
Enquiry 
Acknowledge 

Bell 

Backspace 
Horizontal tabulation 


Line feed 

Vertical tabulation 
Form feed 
Carriage return 
Shift out 

Shift in 

Data link escape 
Device control 1 
Device control 2 
Device control 3 


Device control 4 

Negative acknowledge 
Synchronous idle 

End of transmission block 
Cancel 

End of medium 
Substitute 

Escape 

File separator 

Group separator 


Record separator 
Unit separator 
Space 
Exclamation point 
Quotation marks 


Number sign 
Dollar sign 
Percent sign 
Ampersand 
Apostrophe 
(Continued) 
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ASCII Character Set 


Table C-1. ASCII Character Set and Collating Sequence (Continued) 


Collating Graphic 

Sequence ASCII Code or 

Position (Hexadecimal) Mnemonic Name or Meaning 
40 28 ( Opening parenthesis 
41 29 ) Closing parenthesis 
42 2A - Asterisk 

43 2B + Plus 

44 2C ; Comma 

45 2D - Hyphen 

46 2E : Period 

47 2F / Slant 

48 30 0 Zero 

49 31 1 One 

50 32 2 Two 

51 33 3 Three 

52 | 34 4 Four 

03 35 5 Five 

54 36 6 Six 

55 37 7 Seven 

56 38 8 Eight 

57 39 9 Nine 

58 3A ; Colon 

59 3B é Semicolon 

60 3C < Less than 

61 3D = Equal to 

62 3E > Greater than 
63 3F ? Question mark 
64 40 @ Commercial at 
65 Al A Uppercase A 
66 42 B Uppercase B 
67 43 C Uppercase C 
68 44 D Uppercase D 
69 45 E Uppercase E 
70 46 F Uppercase F 
71 47 G Uppercase G 
72 48 H Uppercase H 
73 49 I Uppercase I 
74 4A J Uppercase J 
75 4B K Uppercase K 
76 4C L Uppercase L 
77 AD M Uppercase M 
78 4E N Uppercase N 
79 AF O Uppercase O 


(Continued) 
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ASCII Character Set 


Table C-1. 


Collating 
Sequence 
Position 


ASCII Code 


(Hexadecimal) 
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Graphic 
or 
Mnemonic 


(oo mE +’) | + ie aS aed CHNADOV 


goo og ho Ao 


fade rtnr vos 


ASCII Character Set and Collating Sequence (Continued) 


Name or Meaning 


Uppercase P 


- Uppercase Q 


Uppercase R 
Uppercase S 
Uppercase T 
Uppercase U 
Uppercase V 
Uppercase W 
Uppercase X 
Uppercase Y 


Uppercase Z 


Opening bracket 


Reverse slant 


Closing bracket 


Circumflex - 


; Underline 


Grave accent 
Lowercase a 
Lowercase b 
Lowercase c 


Lowercase d 
Lowercase e 
Lowercase f 
Lowercase g 
Lowercase h 
Lowercase i 

Lowercase j 

Lowercase k 
Lowercase ] 

Lowercase m 


Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 
Lowercase 


gd eetunnavos 


(Continued) 
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ASCII Character Set 


Table C-1. ASCII Character Set and Collating Sequence (Continued) 


Collating Graphic 

Sequence ASCII Code or 

Position (Hexadecimal) Mnemonic Name or Meaning 
120 78 X Lowercase x 
121 79 "y Lowercase y 
122 TA Z Lowercase z 
123 7B { Opening brace 
124 7C | Vertical line 
125 7D } Closing brace 
126 7E oe Tilde 

127 7F DEL Delete 


ASCII codes 80 through FF hexadecimal (not listed in this table) are ordered as equal 
to the space (ASCII code 20 hexadecimal). 
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Root mean square relative error 5-5 
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C calling the Math Library 4-9; B-2 
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CABS function 8-34 
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Call-by-reference 3-2; A-1 
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(scalar) 3-3 

Call-by-reference versus call-by-value 
matrix 3-6 

Call-by-value 3-4; A-1 

Call-by-value logic diagram (scalar) 3-5 

Calling FORTRAN and the Math Library 
from Ada 4-7 

Calling routines 3-1 

Calls 3-1 

Calls from languages 4-1 

CCOS function 8-36 

CEXP function 8-38 

CLOG function 8-40 

Complex numbers 2-7 

CONJG function 8-42 

COS function 8-44 

COSD function 8-48 

COSH function 8-50 

COSSIN routine 9-5 

COTAN function 8-52 

CSIN function 8-54 

CSQRT function 8-56 

CYBIL example 4-11; B-2 

CYBIL program using 
MLT$COMPLEX 4-12 
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DABS function 8-58 

DACOS function 8-60 

DASIN function 8-64 

DASNCS routine 9-7 

Data descriptor A-1 

Data types for Ada MATH_LIBRARY 
functions 4-5 

DATAN function 8-68 

DATAN2 function 8-72 

DCOS function 8-76 

DCOSH function 8-80 

DDIM function 8-82 

Debug utility 1-2; B-2 

Default error values 2-7 

DEULER routine 9-8 

DEXP function 8-84 

Diagnostic messages 3-2; B-2 

DIM function 8-88 

DINT function 8-89 

DLOG function 8-90 


Math Library Index-l 


DLOG10 function 


DLOG10 function 8-94 
DMOD function 8-98 
DNINT function 8-100 
Domain A-1 
Double precision floating-point 
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DPROD function 8-101 
DSIGN function 8-102 
DSIN function 8-104 
DSINH function 8-108 
DSNCOS routine 9-10 
DSQRT function 8-110 
DTAN function 8-112 
DTANH function 8-116 
DTOD function 8-118 
DTOI function 8-122 
DTOX function 8-126 
DTOZ function 8-128 
Dummy argument A-1 


E 


Entry point 1-8; A-2 

ERF function 8-130 

ERFC function 8-132 

Error A-2 

Error handling 5-1; 7-6 

EXP function 8-134 

Exponentiation functions 
Arguments and results 6-11 
Domains and ranges 6-8 

Exponentiation routine (see also 
routine) A-2 

Exponentiation using Ada 4-7 

EXTB function 8-138 

External routine A-2 


F 


Floating-point computation rules 2-7 
For better performance 
CYBIL 4-13 
FORTRAN Version 1 4-21 
FORTRAN Version 2 4-22 
FORTRAN function summary 4-23 
FORTRAN Version 1 calling the Math 
Library 4-14; B-2 
FORTRAN intrinsic functions 4-14; 
A-2 
Uses call-by-value or 
call-by-reference 4-14 
FORTRAN Version 2 calling the Math 
Library 
Function descriptions 8-1 
ABS 8-3 
ACOS 8-4 
AIMAG 8-8 
AINT 8-9 
ALOG 8-10 
ALOGI0 8-14 
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AMOD 8-18 
ANINT 8-20 
ASIN 8-22 
ATAN 8-26 
ATANH 8-28 
ATAN2 8-30 
CABS 8-34 
CCOS 8-36 
CEXP 8-38 
CLOG 8-40 
CONJG 8-42 
COS 8-44 
COSD 8-48 
COSH 8-50 
COTAN 8-52 
CSIN 8-54 
CSQRT 8-56 
DABS 8-58 
DACOS_ 8-60 
DASIN 8-64 
DATAN 8-68 
DATAN2 8-72 
DCOS 8-76 
DCOSH 8-80 
DDIM 8-82 
DEXP 8-84 
DIM 8-88 
DINT 8-89 
DLOG 8-90 
DLOG10 8-94 
DMOD 8-98 
DNINT 8-100 
DPROD 8-101 
DSIGN 8-102 
DSIN 8-104 
DSINH 8-108 
DSQRT 8-110 
DTAN 8-112 
DTANH 8-116 
DTOD 8-118 
DTOI 8-122 
DTOX 8-126 
DTOZ 8-128 
ERF 8-130 
ERFC 8-132 
EXP 8-134 
EXTB 8-138 
IABS 8-140 
IDIM 8-141 
IDNINT 8-142 
INSB 8-144 
ISIGN 8-146 
ITOD 8-148 
ITOI 8-150 
ITOX 8-152 
ITOZ 8-154 
MOD 8-156 
NINT 8-158 
RANF 8-159 


RANGET 8-162 


RANSET 8-163 


Function descriptions 
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Function name 


Function name A-2 
Functions available 1-3 
Bit manipulation 1-7 
Conversion and 
maximum/minimum 1-6 


G 


Generic and specific names - 8-2 


SIGN 8-164 
SIN 8-166 
SIND 8-168 
SINH 8-170 
SQRT 8-174 
SUMIS 8-178 
TAN 8-180 
TAND 8-182 
TANH 8-184 
XTOD 8-186 
XTOI 8-188 
XTOX 8-190 
XTOZ 8-194 
ZTOD 8-196 
ZTOI 8-198 
ZTOX 8-200 
ZTOZ 8-202 


Error 1-7 


Exponential 1-4 
Hyperbolic 1-5 
Logarithmic 1-4 
Random number 1-7 
Trigonometric 1-5 


Glossary A-1 


H 


HYPERB routine 9-12 


I 


IABS function 8-140 

IDIM function 8-141 

IDNINT function 8-142 

In case you need assistance 11 
Indefinite value A-2 

Infinite value A-2 

Inline versus out-of-line routines 3-7 
Inlined functions 4-14, 28 

Input domains and output ranges 6-6 


Input errors 


Call-by-reference error handling 5-3 
Call-by-value error handling 5-3 
Input range A-2 

INSB function 8-144 

Integer number types 2-2 


Introduction 1-1 


ISIGN function 8-146 
ITOD function 8-148 
ITOI function 8-150 

ITOX function 8-152 
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ITOZ function 8-154 


L 


Language matrix 3-6 


LIB99 1-2; B-2 
LISP 4-1; B-2 
Logical flow of call-by-reference error 
handling 5-4 


M 


Quintic 


Machine round-off error 5-2; A-2 


Manual organization 8 


Mathematical conventions 10 
MOD function 8-156 


N 


NINT function 8-158 


NOS/VE condition handler 

Condition handling 5-6; B-2 

Error processing 5-6 

NOS/VE math library environment 1-2 
Number types 2-1; A-3 

Complex numbers 2-7 

Double precision floating-point 


O 


numbers 2-5 
Integer 2-2 


Single precision floating-point 


numbers 2-3 


Ordering printed manuals B-1 


Output range 6-6; A-3 


P 


Parameter list 7-2 
For single argument vector math 


functions 7-2 


Scalar, vector 7-3 


Vector, scalar 


Vector, vector 17-4 


7-4 


Pascal calling the Math Library 
Pascal calling routines 4-28; B-2 
Pascal math function attributes 4-29 
Pascal predefined functions 4-28 
Processing error 5-2 
Prolog 4-1; B-2 


Q 


Quintic A-3 


Math Library Index-3 


RANF function 


R 


RANF function 8-159 

Range A-3 

RANGET functionfunction 8-162 

RANSET function 8-163 

Related manuals B-1 

Relative error A-3 

Result array and source array 
descriptors 7-5 

Root mean square relative error <A-3 

Routine A-3 

Routines 3-1 

Routines and calls 3-1 


S 


Scalar A-3 
Scalar classification tables 6-1 
SIGN function 8-164 
SIN function 8-166 
SINCOS routine 9-13 
SINCSD routine 9-15 
SIND function 8-168 
Single precision floating-point 
numbers 2-3 
Nonstandard 2-4 
Standard 2-3 © 
SINH functionfunction 8-170 
SQRT function 8-174 
Stride A-3 
Submitting comments 11 | 
Summary of math functions 6-2 
Summary of NOS/VE floating-point 
representation 2-5 
SUMI1S function 8-178 
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ZTOZ function 


T 


TAN function 8-180 
TAND function 8-182 
TANH function 8-184 
Types of processing errors 
Algorithm 5-2 
Machine round-off 5-2 
Typographical conventions 10 


U 
Units in the last place (ulp) A-4 


Vv 


Vector A-4 
Vector error handling 7-6 
Vector function calling routines 7-1 
Vector functions 7-1 
Double argument vector math 
functions 7-3, 4 
Single argument vector math 
functions 7-2 
Vector processing 7-1 
Vectorization A-4 
VX/VE 7; B-2 


».4 


XTOD function 8-186 
XTOI function 8-188 
XTOX function 8-190 
XTOZ function 8-194 


Z 


ZTOD function 8-196 
ZTOI function 8-198 
ZTOX function 8-200 
ZTOZ function 8-202 
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We would like your comments on this manual to help us improve it. Please take a few minutes to fill out 
this form. 


Who are you? How do you use this manual? 
DO Manager 0 As an overview 

D Systems analyst or programmer O To learn the product or system 
0 Applications programmer O For comprehensive reference 

O Operator DO For quick look-up 

DO Other O Other 


What programming languages do you use? 


How do you like this manual? Answer the questions that apply. 
Yes Somewhat No 


oO D O Does it tell you what you need to know about the topic? 

oO Oo O Is the technical information accurate? 

oO oO O Is it easy to understand? 

Oo oO O Is the order of topics logical? 

o Oo O Can you easily find what you want? 

oO D O Are there enough examples? 

oO o O Are the examples helpful? (0 Too simple? © Too complex?) 
0 Oo O Do the illustrations help you? 

oO a) O Is the manual easy to read (print size, page layout, and so on)? 
o oO O Do you use this manual frequently? 


Comments? If applicable, note page and paragraph. Use other side if needed. 


_ Check here if you want a reply: O 


ame Company 
Address Date 


Phone 


Please send program listing and output if applicable to your comment. 


Quick Index 


The following quick index summarizes the math functions and their Math Library 
names, describes each function, and provides a page reference to the complete 
description in chapter 8. 


Function 


ABS 
ACOS 
AIMAG 
AINT 
~ ALOG 


ALOG10 
AMOD 
ANINT 
ASIN 
ATAN 


ATANH 
ATAN2 


CABS 
CCOS 
CEXP © 
“CLOG 
CONJG 


COS. 
COSD 
COSH 
COTAN 
CSIN 


CSQRT 


DABS 
DACOS 
DASIN 
DATAN 
DATAN2 


DCOS 
DCOSH 
DDIM 
DEXP 
DIM 


Description 


Absolute value 

Inverse cosine 

Imaginary part of a complex argument 
Truncation . 
Natural logarithm 


Common logarithm (base 10) 

Returns the remainder of a ratio (uses real numbers) 
Nearest whole number 

Inverse sine 

Inverse tangent 


Inverse hyperbolic tangent 
Inverse tangent of the ratio of two arguments 


Complex absolute value 
Complex cosine 

Complex exponential (base e) 
Complex natural logarithm 
Conjugate 


Cosine 

Cosine in degrees 
Hyperbolic cosine 
Cotangent 
Complex sine 


Complex square root 


Double precision absolute value 

Double precision inverse cosine 

Double precision inverse sine 

Double precision inverse tangent 
Double precision inverse tangent of the ratio of two 
arguments 


Double precision cosine 

Double precision hyperbolic cosine 
Double precision positive difference 
Double precision exponential (base e) 
Positive difference 


Page Number 


8-3 
8-4 
8-8 
8-9 
8-10 


8-14 | 


.- 8-18 
8-20 
8-22 
8-26 


8-28 
8-30 


8-34 
8-36 
8-38 
8-40 
8-42 


8-44 
8-48 
8-50 
8-52 
8-54 


8-56 


8-58 
8-60 
8-64 
8-68 
8-72 


8-76 
8-80 
8-82 
8-84 
8-88 


Function 


DINT 
DLOG 
DLOG10 
DMOD 


DNINT 


DPROD 
DSIGN 
DSIN 
DSINH 


DSQRT 
DTAN 
DTANH 
DTOD 


DTOI 
DTOX 


DTOZ 


ERF 

ERFC 
EXP | 
EXTB 


IABS 
IDIM 
IDNINT 
INSB 
ISIGN 


ITOD 


‘ITO! 
ITOX 
ITOZ 


MOD 
NINT 


RANF 
RANGET 
RANSET 


Description 


Double precision truncation 

Double precision natural logarithm 

Double precision common logarithm (base 10) 
Returns the remainder of a ratio (uses double 
precision numbers) | 

Double precision nearest whole number 


‘Double precision product 


Double precision transfer of sign 
Double precision sine 
Double precision hyperbolic sine 


Double precision square root 

Double precision tangent 

Double precision hyperbolic tangent 

Exponentiation with double precision base and double 
precision exponent 


Exponentiation with double precision base and integer 
exponent 

Exponentiation with double precision base and real 
exponent 

Exponentiation with double precision base and complex 
exponent 


Computes the error function 

Computes the complementary error function 
Exponential (base e) 

Extract bits 


Integer absolute value 

Integer positive difference 
Double precision nearest integer 
Insert bits 

Integer transfer of sign 


Exponentiation with integer base and double precision 
exponent 

Exponentiation with integer base and integer exponent 
Exponentiation with integer base and real exponent 
Exponentiation with integer base and complex 
exponent 


Returns the remainder of a ratio (uses integers) 
Nearest integer 


Generates the next random number in a series 
Returns the current random number seed of a task 
Sets the seed for the random number generator 


Page Number 


8-89 
8-90 
8-94 
8-98 


8-100 


8-101 
8-102 
8-104 
8-106 


8-110 
8-112 
8-116 
8-118 


8-122 
8-126 


8-128 


8-130 
8-132 
8-134 
8-138 


8-140 
8-141 
8-142 
8-144 
8-146 


8-148 
8-150 
8-152 
8-154 
8-156 
8-158 
8-159 


8-162 
8-163 


Function 


SIGN 
SIN 
SIND 
SINH 
SQRT 
SUMIS 


TAN 
TAND 
TANH 


XTOD 
XTOI 
XTOX 
XTOZ 
ZTOD 
ZTOI 


ZTOX 
ZTOZ 


Description 


Transfer of sign 

Sine 

Sine in degrees 
Hyperbolic sine 

Square root 

Sum of 1 bits in one word 


Tangent 
Tangent in degrees 
Hyperbolic tangent 


Exponentiation with real base and double precision 
exponent 

Exponentiation with real base and integer exponent 
Exponentiation with real base and real exponent 
Exponentiation with real base and complex exponent 


Exponentiation with complex base. and double precision 
exponent 

Exponentiation with complex base and integer 
exponent 

Exponentiation with complex base and real exponent 
Exponentiation with complex base and complex 
exponent 
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8-164 
8-166 
8-168 
8-170 
8-174 
8-178 


8-180 
8-182 
8-184 
8-186 
8-188 
8-190 
8-194 
8-196 
8-198 


8-200 
8-202 
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